CLI reference

Every Tonbo Artifacts subcommand and flag.

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
`workspace create`	Create a new workspace (3-phase BYO provisioning)
`workspace list`	List your workspaces
`workspace show`	Print one workspace's details
`workspace delete`	Soft-delete a workspace
`mount`	Mount a workspace at a local path
`unmount`	Cleanly unmount a workspace
`key create`	Mint a service token
`key list`	List your service tokens
`key revoke`	Revoke a service token
`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; currently stubbed)
`stats`	Workspace-wide aggregates (Phase 2; currently stubbed)
`migrate`	Bulk import (Phase 2; currently stubbed). Use rclone / `aws s3 cp`.

`login`

artifacts login [--token <bearer>]

Opens a browser to https://tonbo.io/login by default. Stores credentials at ~/.config/artifacts/credentials.json (mode 0600). Pass --token <bearer> (a Supabase JWT or an art_* service token) to skip the browser on headless hosts.

`logout`

artifacts logout

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

`workspace create`

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

<name> matches ^[a-z][a-z0-9-]{0,38}[a-z0-9]$. Each flag has an ARTIFACTS_S3_* env var fallback (see the Workspaces guide for the full table).

Output on success:

Phase 1: reserving artifacts://<handle>/<name> on the orchestrator
Workspace ... reserved (status=pending_format, key prefix={u_…_w_…}:)
Phase 2: running juicefs format with local BYO credentials
Phase 3: confirming format completion with the orchestrator
Workspace artifacts://<handle>/<name> is active.
Cached BYO credentials at ~/.config/artifacts/byo-credentials (mode 0600);
future mounts will use them automatically.

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

`workspace list / show / delete`

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

--yes skips the interactive confirmation prompt.

`mount`

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

Default is daemonized (background). --foreground keeps FUSE attached to the terminal, useful for debugging.

--manifest <path> is for ops/debug: mount from a pre-recorded manifest JSON instead of issuing a new mount session. Only the mountpoint is positional in that case.

`unmount`

artifacts unmount <mountpoint>

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

`key create / list / revoke`

artifacts key create --workspace <name> --mode rw|ro --ttl <duration> [--name <label>]
artifacts key list
artifacts key revoke <key-id>

The new key value is printed once. --ttl accepts 1h, 24h, 30d, etc.

`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/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
`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`
`ARTIFACTS_S3_PREFIX`	`workspace create`	default for `--prefix`
`AWS_REGION` / `AWS_DEFAULT_REGION`	fallback for region
`ARTIFACTS_DOWNLOAD_HOST`	`install.sh`	override default download URL
`ARTIFACTS_VERSION`	`install.sh`	pin a specific build