CLI reference

artifacts <command> [options]

Global flags (apply to every command):

Flag	Meaning
--verbose / -v	Debug logging
--quiet / -q	Warnings + errors only
--trace	Trace logging
--format json	Machine-readable output (where supported)
--no-color	Disable colour output
--version / -V	Print version

Commands

Command	Purpose
login	Authenticate against the orchestrator
logout	Forget saved credentials
whoami	Print the currently authenticated identity
workspace create	Create a workspace; mount it too if a mountpoint is given
workspace list	List your workspaces
workspace show	Print one workspace's details
workspace delete	Soft-delete a workspace
inspect	Inspect a workspace's metadata keyspace
platform	Platform-operator subcommands (tenant, grant, ticket)
mount	Mount a workspace at a local path
unmount	Cleanly unmount a workspace
storage set	Persist BYO bucket credentials to local cache
storage show	Print masked cache contents
storage clear	Remove the BYO cache
status	Per-mount health & metrics (Phase 2; prints "not yet implemented")
stats	Workspace-wide telemetry aggregates (Phase 2; prints "not yet implemented")
migrate	Bulk import (Phase 2; prints "not yet implemented"). Use rclone / aws s3 cp.

login

artifacts login [--manual-code]

Opens a browser to https://user.tonbo.dev/login by default. Stores credentials at ~/.config/tonbo/artifacts/credentials.json (mode 0600). Use --manual-code for SSH sessions, cloud shells, and containers where the browser cannot reach the CLI callback.

logout

artifacts logout

Removes the credentials file. Doesn't touch the BYO storage cache.

workspace create

artifacts workspace create <name> [mountpoint] \
    [--backend managed|byo] \
    [--bucket <bucket>] \
    [--endpoint <s3-url>] \
    [--region <region>] \
    [--cache-profile interactive|benchmark|custom]

<name> matches ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$ (letters, digits, -, _; up to 63 characters). Each flag has an ARTIFACTS_S3_* env var fallback (see the Workspaces guide for the full table).

Pass a [mountpoint] to mount the new workspace in the same command, equivalent to workspace create followed by mount. The mountpoint directory is created if missing and the mount daemonizes as usual:

artifacts workspace create my-workspace /mnt/work

Output on success:

Workspace my-workspace is active.

Re-running the same command on a pending_format workspace resumes provisioning from the last successful step.

workspace list / show / delete

artifacts workspace list
artifacts workspace show <name>
artifacts workspace delete <name> [--yes]

--yes skips the interactive confirmation prompt.

The workspace argument accepts three forms in every command (create, show, delete, mount):

Form	Example	When to use
<name>	my-workspace	Default; resolves to your own handle
<handle>/<name>	tzu/my-workspace	Unambiguous, useful when scripting
artifacts://<handle>/<name>	artifacts://tzu/my-workspace	Fully-qualified URI; same effect as the slash form

mount

artifacts mount <workspace> <mountpoint> \
    [--read-only] \
    [--foreground|-f] \
    [--cache-profile <profile>] \
    [--cache-root <dir>] [--cache-size <MiB>]

artifacts mount --manifest <path> <mountpoint> \
    [--read-only] \
    [--foreground|-f] \
    [--cache-profile <profile>] \
    [--cache-root <dir>] [--cache-size <MiB>]

Default is daemonized (background). --foreground / -f keeps FUSE attached to the terminal, useful for debugging. --read-only mounts the workspace read-only; there is no -r short form.

--manifest <path> mounts from supplied manifest material instead of issuing a new mount session. Platform worker agents use this form when they inject a manifest file into the worker machine; ops can also use it to replay a saved manifest. Only the mountpoint is positional in that case. Worker flags may narrow access with --read-only, but cannot widen a read-only manifest to writable.

For platform-issued mount tickets (see platform ticket), pass the ticket and the material used to verify its signature:

Flag	Meaning
--ticket <token>	Mount-session ticket value
--ticket-file <path>	Read the ticket from a file instead of the flag
--ticket-public-key <path>	Public key to verify the ticket signature
--ticket-jwks-url <url>	JWKS endpoint to fetch verification keys
--ticket-skip-signature-verification	Skip signature verification (dev/testing only)

unmount

artifacts unmount <mountpoint>

Calls fusermount3 -u. Equivalent to kill -TERM on the daemon.

key

API keys (tbo_*) are issued and managed in your User Center account at https://user.tonbo.dev, not from the CLI. Export the key as TONBO_API_KEY and the CLI and SDK pick it up automatically; no artifacts login is needed. See API keys.

export TONBO_API_KEY=tbo_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
artifacts mount my-workspace /mnt/work

storage set / show / clear

artifacts storage set [--access-key-id ...] [--secret-access-key ...]
                      [--session-token ...] [--region ...]
artifacts storage show
artifacts storage clear

Manages the local BYO credential cache at ~/.config/tonbo/artifacts/byo-credentials (mode 0600). set with no flags captures the current ARTIFACTS_S3_* env vars.

Environment variables the CLI reads

Variable	Used by	Effect
TONBO_API_KEY	all commands	User-Center-issued tbo_* API key; auto-detected for headless auth
ARTIFACTS_S3_ACCESS_KEY_ID	workspace create, mount	BYO bucket access key
ARTIFACTS_S3_SECRET_ACCESS_KEY	same	BYO bucket secret
ARTIFACTS_S3_SESSION_TOKEN	same	(optional) STS session token
ARTIFACTS_S3_REGION	same	bucket region
ARTIFACTS_S3_BUCKET	workspace create	default for --bucket
ARTIFACTS_S3_ENDPOINT	workspace create	default for --endpoint
AWS_REGION / AWS_DEFAULT_REGION	fallback for region
ARTIFACTS_VERSION	install.sh	pin a specific build