treadstone-cli 0.3.7

CLI for the Treadstone sandbox service.

Treadstone CLI

Command-line interface for the Treadstone sandbox service.

Installation

From PyPI

pip install treadstone-cli

Pre-built binary

Download the latest release from GitHub Releases. The binary is self-contained and does not require Python.

# macOS / Linux
chmod +x treadstone
sudo mv treadstone /usr/local/bin/

Quick start

# Check that the server is reachable
treadstone system health

# 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
treadstone sandboxes create --template aio-sandbox-tiny --name my-sandbox
# Name rules: 1-55 chars, lowercase letters/numbers/hyphens only,
# and must start/end with a letter or number.

# List sandboxes
treadstone sandboxes list

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

# Print the AI-oriented usage guide
treadstone guide agent
treadstone --skills

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.

Config file

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

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

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

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

# View a single key
treadstone config get base_url

# 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)

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 AI usage guide
--version	Show CLI version
--help	Show help message

Commands

system

Inspect server reachability and other platform-wide state.

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 invite --email [e-mail]   # Invite a user (admin)
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. This keeps browser URLs like sandbox-{name}.treadstone-ai.dev within DNS label limits.

treadstone sandboxes create --template aio-sandbox-tiny --name my-box
treadstone sandboxes create --template aio-sandbox-medium --label env:dev --persist
treadstone sandboxes list
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>

templates

List available sandbox 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 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 health
treadstone --json sandboxes web enable <sandbox-id>
treadstone --json api-keys list

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