Skip to content

CLI quickstart

Goal: from nothing installed to a running Business Central environment with a URL you can open in a browser. Five commands.

1. Install

curl -fsSL https://cli.bcdock.io/install.sh | sh

Other paths (Homebrew, npm, manual binary) on the install page.

Verify:

bcdock version

2. Log in

bcdock auth login

Prompts for your email, sends a one-time code, exchanges it for a long-lived API key stored at ~/.config/bcdock/credentials.json (mode 0600).

If you're scripting this from CI or an agent, skip auth login and set BCDOCK_TOKEN instead — see authentication.

3. See what BC versions are available

bcdock artifacts list --region australiaeast

Lists the BC version × country combinations the platform can provision in that region. Versions with hasVmImage: true provision in ~2 min; the rest take ~15 min for first-time image build.

4. Create an environment

bcdock env create --name my-first-env --version 27 --country au --wait

--wait blocks until the environment is running (or failed). Default timeout is 30 minutes; pre-warmed pools usually return in 1–2 minutes.

Output (truncated):

NAME           STATUS    VERSION   COUNTRY   URL
my-first-env   running   27.0      au        https://my-first-env-a1b2c3d4.bcdock.io/BC/

Get full details including credentials:

bcdock env get my-first-env -o json | jq

Open it in a browser:

bcdock env open my-first-env

5. Hibernate when you're done

bcdock env hibernate my-first-env --wait

Saves the environment state to blob storage and frees the pool slot. Billing drops to the stored rate (~A$25/month for a typical env). Resume any time:

bcdock env resume my-first-env --wait

Or delete entirely:

bcdock env delete my-first-env --force --wait

Next steps

  • Authentication — API key vs JWT, scopes, when to use each credential path
  • Concepts — what a pool is, what hibernation costs, how the billing model works
  • Exit codes — what to do when a script gets a non-zero exit
  • Command reference — every verb, every flag

Troubleshooting

bcdock: command not found — the install script puts the binary in /usr/local/bin. Make sure that's on your PATH.

error: not authenticated (exit 3) — run bcdock auth login again, or set BCDOCK_TOKEN.

env create hangs past the timeout — first-time image build for an unseen version × country combo can take ~15 min. Re-run with --wait-timeout 30m or check status periodically with bcdock env get <name>.

Long-running command in an agent session — pass run_in_background to the agent's Bash tool so the session stays free. The agent gets a notification when the command exits.