kibo CLI

With the kibo command line, you create Workspaces, work inside them, and script both. This page covers the commands you use most, how kibo waits for results, and how to repeat a command safely. Every flag of every command is listed under kibo commands.

PrerequisitesCopy Anchor Link

• kibo installed from the release set. It has three builds: Linux/amd64, and macOS on Apple Silicon or Intel. For which one to choose, see Identity and enrollment.
• An enrolled Operator identity on your machine. See Identity and enrollment.

No other token or password is needed. See How kibo connects.

A first sessionCopy Anchor Link

Create a Workspace and keep its ID in a variable:

workspace_id=$(kibo workspace create --template "$template_id" --memory 1G -q)
kibo workspace get "$workspace_id"

• create waits until the Workspace is available, for up to one hour. See Waiting for results.
• -q prints only the ID. Without it, create prints a summary: the first line is the Workspace ID and state, and the last line gives the command to open a terminal.
• Later commands accept the first few characters of a Workspace or Volume ID, as long as they identify it uniquely, for example kibo workspace get ws-01k6.

Run a command, copy a file in and back out, and open a terminal:

kibo workspace exec "$workspace_id" -- /bin/echo ready
printf 'release installation smoke\n' > local.txt
kibo workspace file put "$workspace_id" local.txt /data/local.txt
kibo workspace file get "$workspace_id" /data/local.txt downloaded.txt
cmp local.txt downloaded.txt
kibo workspace terminal "$workspace_id"

Type exit in the remote shell to leave the terminal.

Commands by taskCopy Anchor Link

Each row shows one typical command. The task links to the page that covers the rest of that group. Replace template_id, workspace_id, and volume_id with real IDs.

Managing WorkspacesCopy Anchor Link

Working inside a WorkspaceCopy Anchor Link

Network and dataCopy Anchor Link

Waiting for resultsCopy Anchor Link

By default, workspace create, start, stop, and delete wait. After ctrl accepts the command, kibo keeps querying its result until the Workspace is AVAILABLE, STOPPED, or DELETED. It does not send the command again while it waits.

In a terminal, a progress line on standard error refreshes as the state changes. Otherwise, kibo prints a single line when the wait starts.

--wait-timeout limits the whole wait, one hour by default, and --timeout limits each request. --no-wait returns as soon as ctrl accepts the command, while the Workspace may still be CREATING or STOPPING. For these flags on every command, see Common command flags.

• When creation fails, the error message gives the reason.
• When create or start gets no response after submitting the request, kibo sends it up to three times in total with the same ID and input. Stop and delete are not resent automatically. If there is still no result, kibo prints the ID so you can query it later.
• Expiration actions are carried out by ctrl, so exiting kibo does not affect them.

Using kibo in scriptsCopy Anchor Link

When a waiting command succeeds, the JSON output is a WorkspaceCommandResult; its fields are listed under JSON output. result.current_workspace comes from one more query after the command completed. When that query fails, it is null and the reason is in result.current_error, but the command itself still succeeded.

With --no-wait, the output is the Workspace at the time ctrl accepted the command. Before an operation that depends on the current state, query again with kibo workspace get.

Command IDs and unknown resultsCopy Anchor Link

Every write command carries a command ID, which makes it safe to repeat. kibo generates one unless you pass --command-id. Pass your own when a script may need to run the same command again:

kibo workspace stop "$workspace_id" --command-id stop-example
kibo --json workspace command get "$workspace_id" stop-example

A command with an ID ctrl already has is not submitted again:

• For the same Workspace and kind of command, kibo reports the result of the existing command. While that command is still in progress, kibo waits for it; with --no-wait, it returns the in-progress record.

• For another Workspace or another kind of command, the command fails. Use a different ID.

• If the original request is still in flight when you rerun, ctrl accepts only one of the two and rejects the other as a conflict. The command never runs twice.

• When a request times out or its result is unknown, query with the same command ID, or rerun the same command with the same ID and parameters. A rerun returns the original command's result; check the current state separately with kibo workspace get.

• A command that cannot be found does not mean the request failed. Do not resend with a different ID because of it.

• For the rules shared by all write commands, including expected revisions, see Command IDs and expected revisions and Command IDs on the native API page.

How kibo connectsCopy Anchor Link

kibo reaches Kibotos over two paths:

For certificates, the identity directory, and proxies, see Identity, configuration, and connections.

Next stepsCopy Anchor Link

• Core concepts: Workspaces, Volumes, and their states.
• Guarantees and limits: when data is kept.
• kibo CLI reference: global flags, exit codes, and the JSON output format.
• API overview: the same operations from your own program.