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
How it works
- You give the CLI a token and a workspace, from the environment or as options.
- 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).
- Commands that start asynchronous work, such as VM create, return an
operation_id. You check it withibee ops getuntil it has finished. - 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
Check the 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).
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_idsis--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@FILEreads 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.
- The CLI sends only what you pass. Copy
--cpu,--ram-mband--disk-gbfrom the plan, and--os-typeand--os-distrofrom the image. --billing-interval HOURLY(orMONTHLY) reads the--plan-idplan and sends itsbilling_catalogwith the chosenbilling_optionsentry merged in, as the portal does.vms resizeandgpus resizetake the same two options for the target plan, and the plan’s exact--cpu,--ram-mband--disk-gb; there--plan-idis only used for the lookup and is not sent. You can pass the whole selection yourself with--billing-catalog JSONinstead.MONTHLYis a one-month commitment: delete and resize answer409 VM_COMMITTEDuntil it ends.vms deleteneeds--public-ip-actionwhen the VM has an automatically assigned public IP:releasegives the address up,reservekeeps 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 with400.
Common commands
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.
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:
To wait in a script, poll every few seconds (this uses jq to read the status):
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:
With -o json the same fields, plus the raw body, are printed on stderr as {"error": {...}}.
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,--alland the like. Check operations withibee ops get OPERATION_ID, and page lists with--limitand--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
Related pages
- Python SDK, the library the CLI is built on
- Asynchronous operations: what
ibee ops getreports - Examples: a
cli.shfor every product ibee-clion PyPI and on GitHub
