treadstone-cli 0.8.4

CLI for the Treadstone sandbox service.

Treadstone CLI

Command-line interface for the Treadstone sandbox service.

Installation

Recommended: release installer

curl -fsSL https://treadstone-ai.dev/install.sh | sh

Windows PowerShell:

irm https://treadstone-ai.dev/install.ps1 | iex

The installer downloads the correct binary for your platform and verifies checksums when available.

Alternative: PyPI

pip install treadstone-cli

Quick start

Human workflow

# Optional: point the CLI at your own deployment
export TREADSTONE_BASE_URL="http://localhost:8000"

# Check that the server is reachable
treadstone system

# Register an account (first time only)
treadstone auth register

# Log in and save a local session for the active base URL
treadstone auth login

# Create an API key for non-interactive use and save it locally
treadstone api-keys create --name my-key --save

# Create a sandbox (defaults to aio-sandbox-tiny unless overridden)
treadstone sandboxes create --name my-sandbox
# Name rules: 1-55 chars, lowercase letters/numbers/hyphens only,
# and must start/end with a letter or number. Names are only unique per user.

# List sandboxes
treadstone sandboxes

# Optional: change the default template for future creates
treadstone config set default_template aio-sandbox-medium

# Create a browser hand-off URL for a human
treadstone sandboxes web enable <sandbox-id>

# Print the built-in agent skill
treadstone guide agent
treadstone --skills

Agent workflow

For automation and AI agents, prefer JSON output and capture the returned sandbox ID from command output.

treadstone --json system
treadstone auth register --email [e-mail] --password YourPass123!
treadstone auth login --email [e-mail] --password YourPass123!
treadstone --json api-keys create --name automation --save

treadstone --json templates
treadstone --json sandboxes create --name my-sandbox
treadstone --json sandboxes get <sandbox-id>
treadstone --json sandboxes web enable <sandbox-id>

treadstone guide agent
treadstone --skills

Treat name as a human-readable label only. Follow-up sandbox commands require SANDBOX_ID, and browser URLs should come from urls.web, web_url, or open_link rather than being constructed from the sandbox name.

Configuration

The CLI reads configuration from three sources, in order of priority:

Priority	Source	Example
1 (highest)	CLI flags	--base-url https://... --api-key ts_...
2	Environment variables	TREADSTONE_BASE_URL, TREADSTONE_API_KEY
3 (lowest)	Config file	~/.config/treadstone/config.toml

Saved login sessions are stored separately in ~/.config/treadstone/session.json and are only used when no API key is configured for the active base URL.

For treadstone sandboxes create, template resolution works like this:

1. --template
2. TREADSTONE_DEFAULT_TEMPLATE
3. default_template in ~/.config/treadstone/config.toml
4. built-in default aio-sandbox-tiny

Config file

Location: ~/.config/treadstone/config.toml

[default]
base_url         = "https://your-server.example.com"
api_key          = "ts_live_xxxxxxxxxxxx"
default_template = "aio-sandbox-medium"

You can manage this file with the config subcommand:

# Set a value
treadstone config set base_url https://your-server.example.com
treadstone config set api_key ts_live_xxxxxxxxxxxx
treadstone config set default_template aio-sandbox-medium

# View current settings (api_key is partially masked)
treadstone config
treadstone config get

# View a single key
treadstone config get base_url
treadstone config get default_template

# Remove a value
treadstone config unset api_key

# Show config file path
treadstone config path

Environment variables

Variable	Description	Default
TREADSTONE_BASE_URL	Base URL of the Treadstone server	https://api.treadstone-ai.dev
TREADSTONE_API_KEY	API key for authentication	(none)
TREADSTONE_DEFAULT_TEMPLATE	Default template for sandboxes create	aio-sandbox-tiny

Global flags

Flag	Description
--base-url URL	Override the server URL
--api-key KEY	Override the API key
--json	Output responses as JSON (useful for scripting)
--skills	Print the built-in agent skill in SKILL.md format for tools like GangGang, Codex, and Cursor
--version	Show CLI version
--help	Show help message

Shortcut groups

Some groups run the most common subcommand when no second-level command is given:

treadstone system      # same as: treadstone system health
treadstone templates   # same as: treadstone templates list
treadstone sandboxes   # same as: treadstone sandboxes list
treadstone config      # same as: treadstone config get

Commands

system

Inspect server reachability and other platform-wide state.

treadstone system
treadstone system health
# Server is healthy

auth

Authentication and user management.

treadstone auth register                 # Create a new account
treadstone auth login                    # Log in and save a local session
treadstone auth logout                   # Clear the saved session for this base URL
treadstone auth whoami                   # Show the current user via API key or session
treadstone auth change-password          # Change your password
treadstone auth users                    # Admins see all users; non-admins see themselves
treadstone auth delete-user <user-id>    # Delete a user (admin)

sandboxes (alias: sb)

Create and manage sandboxes.

Custom sandbox names must be 1-55 characters of lowercase letters, numbers, or hyphens. They must start and end with a letter or number. Sandbox names only need to be unique for the current user. treadstone sandboxes create defaults to aio-sandbox-tiny unless you override it with --template, TREADSTONE_DEFAULT_TEMPLATE, or config key default_template.

treadstone sandboxes
treadstone sandboxes create --name my-box
treadstone sandboxes create --template aio-sandbox-medium --label env:dev --persist
treadstone sandboxes create --template aio-sandbox-large --persist --storage-size 5Gi
treadstone sandboxes list --label env:prod --label team:agent --limit 10
treadstone sandboxes get <sandbox-id>
treadstone sandboxes start <sandbox-id>
treadstone sandboxes stop <sandbox-id>
treadstone sandboxes delete <sandbox-id>
treadstone sandboxes web enable <sandbox-id>
treadstone sandboxes web status <sandbox-id>
treadstone sandboxes web disable <sandbox-id>

Persistent sandbox storage currently supports the preset tiers 5Gi, 10Gi, and 20Gi.

templates

List available sandbox templates.

treadstone templates
treadstone templates list

api-keys

Manage long-lived API keys.

treadstone api-keys create --name ci-bot
treadstone api-keys create --name ci-bot --save
treadstone api-keys create --name temp --expires-in 86400  # 24h
treadstone api-keys create --no-control-plane --data-plane selected --sandbox-id sb123
treadstone api-keys list
treadstone api-keys update <key-id> --data-plane none
treadstone api-keys delete <key-id>

config

Manage local CLI configuration.

treadstone config
treadstone config set default_template aio-sandbox-medium
treadstone config set base_url https://...
treadstone config set api_key ts_...
treadstone config get
treadstone config get base_url
treadstone config unset api_key
treadstone config path

JSON output

Pass --json before any command to get machine-readable JSON output:

treadstone --json sandboxes list
treadstone --json system
treadstone --json sandboxes web enable <sandbox-id>
treadstone --json api-keys list

treadstone sandboxes web enable <sandbox-id> is idempotent: it returns the current active browser hand-off URL when one already exists. If you need a new hand-off URL, disable web access first and then enable it again.

AI Agent usage

Use the CLI as a JSON-first interface when an agent needs to chain commands:

treadstone --json system
treadstone --json templates
treadstone --json sandboxes create --name demo
treadstone --json sandboxes get <sandbox-id>
treadstone --json sandboxes web enable <sandbox-id>

Guidelines:

• Put --json before the subcommand.
• Pass --email and --password explicitly for non-interactive auth flows.
• Sandbox names are only unique for the current user. They are not accepted where SANDBOX_ID is required.
• Browser entry URLs are based on sandbox_id under the hood. Read urls.web, web_url, or open_link from command output instead of constructing URLs manually.
• treadstone --skills prints a built-in SKILL.md document that can be fed to agent runners.

Error handling

The CLI displays user-friendly error messages instead of stack traces:

Error: Connection refused.
  Possible causes:
    - The Treadstone server is not running
    - The --base-url or TREADSTONE_BASE_URL is incorrect
    - A firewall or proxy is blocking the connection
  Detail: ...

Common errors:

Error	Cause	Fix
Connection refused	Server not running or wrong URL	Check treadstone config get base_url
Request timed out	Server slow or unreachable	Retry, or check network
No authentication configured	Missing API key and no saved session	treadstone auth login or treadstone config set api_key <key>
HTTP 401	Invalid or expired API key	Create a new key with treadstone api-keys create
HTTP 404	Resource not found	Verify the resource ID is correct; sandbox names are not accepted where SANDBOX_ID is required