Skip to navigation

CLI

The IBEE CLI is a command-line program, ibee, that manages your IBEE resources from a terminal: VMs, networks, storage, CDN, secrets and container registries. It has one command per API operation (API contract 0.10.0, 231 operations, 51 of them temporarily paused); each command makes that one call and prints the server’s answer. It is built on the Python SDK, and the current version is 0.8.0.

When to use the CLI

You want to…Use
Run a quick command, or write a shell script or CI stepThe CLI (this page)
Call IBEE from inside a Python or TypeScript programThe SDKs
Keep infrastructure in files and review each change before applying itTerraform
Top up, read invoices or manage team membersThe portal: the API doesn’t offer these

How it works

  1. You give the CLI a token and a workspace, from the environment or as options.
  2. Each command calls one API operation. Path parameters are arguments; every other field is an option of the same name. The answer is printed as JSON (or YAML, a table, or just the ID).
  3. Commands that start asynchronous work, such as VM create, return an operation_id. You check it with ibee ops get until it has finished.
  4. When the API refuses a request, the CLI prints the server’s fields and exits with a code that tells you which kind of error it was.

Before you begin

  • Python 3.10 or later and pip.
  • An API token with the permissions your commands need, for example Virtual Machines → Read to list VMs and Edit to create them. See Authentication.
  • Your workspace ID. See Find your workspace ID.

Install and run your first command

1

Install the CLI

pip install --upgrade ibee-cli

This installs the ibee command and the ibee Python SDK it uses.

2

Check the version

ibee --version

It prints ibee-cli 0.8.0. If it shows 0.5, upgrade: the commands on this page don’t work with 0.5 (see Upgrading from 0.5).

3

Set your token and workspace

export IBEE_TOKEN="ibee_prod_key_xxxxxxxxxxxx" # or IBEE_API_TOKEN
export IBEE_WORKSPACE_ID="907479"

Both can also be passed per command with --token and --workspace.

4

List the compute sites

ibee compute sites

This reads only. You see the API’s JSON answer: a sites list with each site’s site_id and name, and a count. You’ll pass a site_id to --site-id when you create a VM.

How commands map to the API

  • Path parameters are arguments, in path order: ibee vms get VM_ID.
  • Every query parameter, header and request-body field is an option of the same name: ssh_key_ids is --ssh-key-ids. The contract’s required fields are required options.
  • Booleans are --name/--no-name. Lists repeat the option (--tags a --tags b). Objects take JSON, and @FILE reads it from a file (--rules @cors.json).

COMMANDS.md lists every command with its API operation, and ibee COMMAND --help shows each option.

Create and delete a VM

Find a site, a plan and an image, then create a VM. The VM is billed from creation until you delete it.

ibee compute sites
ibee compute plans --vm-type cloud --site-id SITE_ID
ibee compute images --vm-type cloud --site-id SITE_ID
ibee vms create --name web-1 --site-id SITE_ID --plan-id PLAN_ID --template-id IMAGE_ID \
--os-type linux --os-distro ubuntu --cpu 1 --ram-mb 2048 --disk-gb 50 \
--billing-interval HOURLY --ssh-keys "$(cat ~/.ssh/id_ed25519.pub)"
ibee ops get OPERATION_ID
ibee vms list --limit 20
ibee vms delete VM_ID --public-ip-action release --yes
  • The CLI sends only what you pass. Copy --cpu, --ram-mb and --disk-gb from the plan, and --os-type and --os-distro from the image.
  • --billing-interval HOURLY (or MONTHLY) reads the --plan-id plan and sends its billing_catalog with the chosen billing_options entry merged in, as the portal does. vms resize and gpus resize take the same two options for the target plan, and the plan’s exact --cpu, --ram-mb and --disk-gb; there --plan-id is only used for the lookup and is not sent. You can pass the whole selection yourself with --billing-catalog JSON instead. MONTHLY is a one-month commitment: delete and resize answer 409 VM_COMMITTED until it ends.
  • vms delete needs --public-ip-action when the VM has an automatically assigned public IP: release gives the address up, reserve keeps it as a Reserved IP (with --reserved-ip-billing-catalog). Leave it out when the VM’s IP is already a Reserved IP; both values are refused with 400.

Common commands

ibee vms get VM_ID
ibee vms stop VM_ID
ibee vms resize VM_ID --cpu 4 --ram-mb 8192 --disk-gb 80 --plan-id PLAN_ID --billing-interval HOURLY
ibee vms backup-policy disable VM_ID
ibee gpus list
ibee buckets create --name assets --region in-south-1
ibee buckets cors set assets --rules @cors.json
ibee buckets credentials create --name ci --permission-type object_rw
ibee block-storage list
ibee cdn list
ibee secrets stores list
ibee vpcs list
ibee reserved-ips list
ibee firewalls list
ibee registries list
ibee load-balancers list

gpus takes the same commands as vms. Commands that delete, revoke, archive, purge, restore or detach ask for confirmation; add --yes to skip it. buckets create needs --region, an Object Storage region identifier such as in-south-1 (not a compute site ID); see Object Storage buckets.

Global options

Global options go before the command.

OptionEnvironment variableDescription
--tokenIBEE_TOKEN (or IBEE_API_TOKEN)API token
--workspace, -wIBEE_WORKSPACE_IDWorkspace ID
--devIBEE_ENV=devUse the development API with an ibee_dev_key_... token
--base-urlIBEE_BASE_URL, then IBEE_ENDPOINTCustom API endpoint
-o, --outputIBEE_OUTPUTjson (default), yaml, table, or id
--jsonSame as -o json
--yes, -yIBEE_ASSUME_YES=1Answer yes to every confirmation
ibee -o id buckets list
ibee -o table vms list

Follow operations

VM create, delete, start, stop, reboot and resize, access and volume changes are asynchronous. The command returns at once with an operation_id, and the work continues on IBEE. Check it until status is succeeded, failed, cancelled or timed_out:

ibee ops get OPERATION_ID

To wait in a script, poll every few seconds (this uses jq to read the status):

while true; do
status=$(ibee ops get OPERATION_ID | jq -r .status)
echo "$status"
case "$status" in succeeded|failed|cancelled|timed_out) break ;; esac
sleep 5
done

See Asynchronous operations for what each status means.

Errors and exit codes

Every error prints the HTTP status and the server’s fields as sent:

Error: HTTP 409
code: VM_COMMITTED
message: ...
request_id: 6f1c2e...

With -o json the same fields, plus the raw body, are printed on stderr as {"error": {...}}.

Exit codeMeaning
0Success
1Declined confirmation, an answer that doesn’t match the contract, or another error
2Usage or configuration error; nothing was sent
4Network error (no HTTP answer)
10–14HTTP 400, 401, 402, 403, 404
15–18HTTP 409, 422, 423, 429
19HTTP 5xx

A command for a paused Object Storage or Container Registry operation exits with 14, the code for HTTP 404, and prints that the operation is temporarily paused.

Retries

Reads are retried on 429, 502, 503 and 504. Writes are retried only on 429 and 503, and only when they carry an idempotency key; an answer with a billing or admission code is never retried, and VM creates never are. Each request times out after 30 seconds, and there are at most 2 retries, waiting Retry-After or 1 second doubling each time.

An idempotency key is a unique string that lets the API recognise a repeated request (see Idempotency). Write commands that take --idempotency-key KEY send it unchanged; without one, a random key is sent. After a retryable failure the CLI prints the key, so you can repeat the command without doing the write twice.

Upgrading from 0.5

  • One command per API operation, generated from the contract. Commands for operations that contract 0.6 removed are gone (vms resize-plan, backup runs and rescheduling, console sessions, Block Storage attach and detach, billing eligibility, and others). New operations have commands: bucket lifecycle, CORS, notifications and custom domains, S3 key revoke, Container Registry, and more.
  • Request fields are options: ibee vms create --name web-1, not a positional name; ibee buckets create --name assets.
  • Client-side helpers are removed: --wait, ops wait, --ssh-key-file, --all and the like. Check operations with ibee ops get OPERATION_ID, and page lists with --limit and --offset.
  • VM create no longer fills in CPU, memory, disk or OS from the plan and image: pass them, plus --billing-interval.
  • The default output is JSON.

See the CLI CHANGELOG for the full list.

Troubleshooting

You seeWhat it meansWhat to do
ibee: command not foundpip installed the command in a folder that isn’t on your PATHUse python3 -m pip install --user ibee-cli and add the folder pip names to PATH, or install in a virtual environment.
No such option: --wait, or Got unexpected extra argument(s) (web-1)A command written for CLI 0.5Rewrite it for 0.6: see Upgrading from 0.5.
Missing option '--name'. (or another option), or Missing argument 'VM_ID'.The API requires that fieldAdd it; ibee COMMAND --help lists the required ones.
billing_catalog is required: pass --billing-interval HOURLY|MONTHLY ...VM create needs a billing termAdd --billing-interval HOURLY.
No API token. Set IBEE_TOKEN (or pass --token). (exit 2)No token was givenSet IBEE_TOKEN. Create tokens under Organization → API Tokens.
No workspace. Set IBEE_WORKSPACE_ID (or pass --workspace). (exit 2)No workspace was givenSet IBEE_WORKSPACE_ID.
Error: HTTP 401, code: invalid_api_key (exit 11)The token is wrong, cut short or from the other environmentCopy the whole token; use --dev only with an ibee_dev_key_ token.
Error: HTTP 403, code: insufficient_scope (exit 13)The token lacks the permission in required_scopeCreate a token with that permission.
Error: HTTP 402, code: billing_denied (exit 12)Billing refused a billable createRead reason; see Billing refusals.
Error: HTTP 409, code: VM_COMMITTED (exit 15)The VM is on a Monthly commitmentWait until the commitment ends.
Exit code 4No HTTP answer (network error)Check your connection, then repeat the command with the --idempotency-key it printed.