kibo CLI reference
This page lists the global flags of kibo, its exit codes, its JSON output format, and its rules for reading and writing local files. Command usage is split across three places by reader:
- For Workspace and Volume operations, see kibo CLI and the topic pages it lists.
- For enrollment and connection configuration, see Identity and enrollment.
- For managing nodes, storage pools, Platforms, and Templates, see the Operator pages Nodes, Storage pools, and Catalog. The columns of
kibo node listare described inlistandget.
For the usage and flags of each command, see kibo commands, which is generated from the kibo source code.
Global flags
These flags can go before or after the subcommand.
| Flag | Default | Description |
|---|---|---|
--endpoint <url> | The address saved in the context | Overrides the ctrl address for this request. When it is not given, the environment variable KIBO_ENDPOINT is checked first, then the value in the context is used. The identity and trusted certificates do not change |
--json | Off | Prints stable JSON, with the result in the result field |
--timeout <duration> | 30s | The timeout of a single request. File uploads and downloads themselves are not limited by it. node drain --wait uses it to limit the whole wait |
Common command flags
The following flags exist only on the commands that use them and must go after the subcommand, for example kibo workspace delete ws-01k6… --yes. Each command's page in kibo commands lists the flags it takes.
| Flag | Description |
|---|---|
--command-id <key> | The command ID of a command that sends changes, generated automatically when not given. Replaying the same ID with the same input does not run the operation again; different input is rejected as a conflict. kibo template publish can derive it from the build result. For the rules, see kibo help command-ids |
-y, --yes | Skips confirmation on commands that ask for it, such as deletions. Required in a non-interactive terminal |
-q, --quiet | Prints only the resource IDs in the result, one per line, for example ws=$(kibo workspace create --template t -q) |
--wide | Adds fields omitted by default: the various revisions, generation, full digests, labels, registration version, and the list of capability names |
-L, --label-column <key> | Repeatable. Shows this label as a column, named after the part of the key after the last / |
--all | Reads all results page by page. Without it, only one page is fetched, and -q prints a note on stderr when there is a next page |
--quiet, --wide, and --json are mutually exclusive.
Commands that wait for the server to finish have --wait-timeout. Its default, 1h or 2h, is listed on each command's page. workspace create/start/stop/delete and template prepare also have --no-wait, which returns as soon as the request is accepted.
A wait timeout or Ctrl-C does not withdraw an operation already submitted. When the result is unknown, replay with the same command ID, or query with kibo workspace command get. Do not resubmit with a different command ID.
Command IDs and expected revisions
Commands that change existing objects follow one set of rules:
- Each write command carries a command ID (
--command-id) and an expected revision. Running it again with the same command ID and the same input only returns the current state and does not take effect twice. The same command ID with different input returnsalready_existswith exit code13. - The expected revision is used for optimistic locking. When it is not given,
kiboreads the current revision first and then submits. If the revision has changed by the time of submission, the server returnsaborted(failed_preconditionfor expiration revisions), andkiboexits with code13without retrying automatically. Read the state again before deciding what to do. - An explicit
--command-idrequires the matching expected-revision flag as well. For manual operations, give neither;kibogenerates a random command ID and reads the current revision. - When the target object does not exist, the exit code is
12.
Size and CPU formats
- Write capacity and memory as a number plus a unit. Units are always binary:
K,M,G,T,Pare equivalent toKi,KiB, and so on.1Gis1 << 30bytes, and no unit means bytes. - Decimal forms such as
KB,MB, andGBare rejected before the request is sent, with a hint to useGorGiBinstead. - Write CPU as cores or millicores:
2,0.5,1500m.
Completion and ID prefixes
kibo completion bash|zsh|fish|powershellprints a completion script. For ID arguments of Workspaces, Volumes, Templates, nodes, Exposures, Egresses, and Resolvers, and for--template,--volume,--workspace,--node,--egress, and--resolver, completion reads the first page of resources from ctrl.- Workspace and Volume ID arguments accept a unique prefix, for example
kibo workspace get ws-01k6. With no match, the command exits with12. With several matches, it exits with2and lists the candidates.
JSON output
- Field names match the API definition and use snake_case. Enums keep their full names; for example,
AVAILABLEin human-readable output isWORKSPACE_STATE_AVAILABLEin JSON. - Besides
result, check thecompletenessanderrorfields. Output does not mean the command succeeded. - The envelope of a write command carries
command_id, whose value is the command ID used this time. You can use it directly to replay or query. Read-only commands have no command ID and do not print this field. Human-readable output shows the same value asCommand ID. workspace create/start/stop/deletethat wait for completion printWorkspaceCommandResult:result.workspace_idis the Workspace ID,result.command_resultis the Workspace when the command completed, andresult.current_workspaceis the current state read afterward. Stop also hasresult.durability.--no-waitprintsWorkspace, with the ID also inresult.workspace_id.
Exit codes
The exit codes of kibo, including those of workspace exec and workspace terminal, are listed in kibo exit codes, generated from the kibo source code.
Error output
- Human-readable output has a single
Error:line, with the stage and reason in parentheses when the server provides them. A specific next step goes on aHint:line. Write commands also printCommand ID:. - The error category, impact, and retryability appear only in the
errorfield of--json. - When a subcommand or flag is misspelled,
Hint:gives the closest match.
Local file input and output
Enrollment key files are read as described in Enrollment key rules.
Reading Egress passwords
Applies to --password-file and --password-stdin of kibo egress create/update:
- One trailing newline (
\nor\r\n) is removed. The remaining characters are the password as is and can include spaces. The password is 1 to 255 bytes. - When only
--usernameis given, the password is prompted for in the terminal without echo. Without a terminal, use one of these two flags. No flag takes the password directly on the command line;--passwordis rejected on every command. - The password never appears in any output, error message, or JSON result.
Writing downloaded files
Applies to kibo workspace file get:
- New files get mode
0600. When an existing regular file is overwritten, its mode is kept. Set a mode with--mode 0640and the like, in the range0000to0777. - Data is written to a temporary file first and replaces the target only after it is fully received. If the transfer fails, the target file is unchanged.
- The target cannot be a symbolic link or a special file.
--modecannot be used when writing to-(standard output).
Identity, configuration, and connections
This page describes the identity, certificate, and configuration rules that ctrl, nodes, and clients share. It answers questions such as "what does this configuration item mean" and "where does this certificate come from, and when does it expire".
kibo commands
This page lists every kibo command by group. Each command's page gives the usage, examples, and flags of the command and its subcommands, generated from the kibo source code.