CLI

The simpcat CLI is installed automatically with the Python package. Install it directly on your shell PATH with:

uv tool install simpcat

For a one-off invocation without installing it, use uvx simpcat. Inside a project managed by uv, uv run simpcat uses that project’s environment; the executable is not expected to appear on the global PATH.

The CLI handles authentication, diagnostics, offline run sync, saved views, and data queries.

Runtime environment variable overrides for the CLI, Python SDK, and spawned reporter are documented in the Environment Variables reference.

Commands

simpcat login

Create an API key in the Simpcat web UI under Settings → API Keys, then authenticate with:

simpcat login

You’ll be prompted for your API key. Pass it directly with:

simpcat login --key sk-your-api-key

Connect to a custom host:

simpcat login --host my-simpcat.example.com

The SIMPCAT_HOST environment variable is also respected when --host is not provided.

simpcat login verifies the key with the server and stores credentials per host in ~/.simpcat/config.toml.

simpcat logout

Remove saved credentials for a host:

# Remove credentials for the default host (app.simpcat.ai)
simpcat logout

# Remove credentials for a specific host
simpcat logout --host my-simpcat.example.com

simpcat sync

Upload orphaned runs that didn’t finish syncing (e.g. after a crash or network failure).

Sync a specific run:

simpcat sync .simpcat/run-20260219_143052-a1b2c3d4/

Scan for and sync all unfinished runs:

simpcat sync --all

The sync command replays the run’s WAL (write-ahead log), uploads any pending logs and media, and marks the run as finished.

Optional: simpcat verify

Most users do not need this during normal setup. Use it when you want a diagnostic summary of the current CLI and reporter configuration:

simpcat verify

This checks:

• Config file exists
• Host configuration
• API key is configured
• Server is reachable and API key is valid
• Reporter mode (online/offline)
• Active environment variable overrides

Exits with code 1 if any check fails — useful in CI or setup scripts.

Offline mode

Set SIMPCAT_MODE=offline before launching training:

SIMPCAT_MODE=offline python train.py

simpcat.init() starts a reporter process for each run, and that reporter inherits the training environment. In offline mode, the reporter collects metrics to the local WAL (write-ahead log) without making any network calls. Use simpcat sync later to upload offline runs.

Offline sync currently treats each unsynced local reporter attempt as its own uploaded run. Fresh offline runs do not have a canonical run ID or run.json until future offline-resume support is added, so restarting from the same save_dir will not automatically continue the same logical run. Use online mode when you need normal multi-process resume semantics.

You can also set mode = "offline" in the [reporter] section of your config file.

Managing runs

Update a run’s mutable metadata:

simpcat run update a1b2c3d4 --name "better name" --notes "baseline rerun"
simpcat run update a1b2c3d4 --clear-notes

Set or remove tags across one or more runs:

simpcat run tag set stage=review owner=ml --runs a1b2c3d4,b5c6d7e8
simpcat run tag rm stage owner --runs a1b2c3d4,b5c6d7e8

Each tag command atomically updates at most 50 runs.

Run deletion is immediate and permanent. The command prints a preview unless you explicitly pass --execute:

# Preview the affected runs
simpcat run delete a1b2c3d4 b5c6d7e8

# Permanently delete them
simpcat run delete a1b2c3d4 b5c6d7e8 --execute

A deletion command accepts at most 10 runs and deletes the entire batch atomically. Run updates, tag changes, and deletion require an API key (browser sessions cannot perform them). Use --format json for machine-readable output.

Managing comparison views

Create a saved web view directly from canonical run IDs:

simpcat view create \
  --name "native parity comparison" \
  --runs jx7913qxssmycqxdk91sf6t79d8bsnmj,jx71p2t5jetemkc93q73fgwdcn8bgdgd

The command prints a shareable URL on the configured app host, such as app.simpcat.ai/?view=.... Use --format json when another program or coding agent needs to consume the view ID and URL. Saved-view creation requires an API key and rejects run IDs outside the key’s organization.

List and rename saved views:

simpcat view list
simpcat view rename jx7viewid --name "final comparison"

Saved-view deletion also previews by default and requires --execute:

simpcat view delete jx7viewid
simpcat view delete jx7viewid --execute

Querying data

The simpcat get namespace is the read-only CLI surface over the documented public API.

simpcat get projects

List all projects in your organization:

simpcat get projects

simpcat get runs

List runs, with optional filters:

# All runs
simpcat get runs

# Filter by project
simpcat get runs --project my-project --limit 10

# Find completed baselines by name, tags, and start time
simpcat get runs \
  --name-contains baseline \
  --state finished \
  --tag model=7b \
  --started-after 2026-08-01

Without --limit, the CLI follows every pagination cursor and returns all matching runs. An explicit limit intentionally bounds the result and reports whether more runs remain.

--name matches exactly; --name-contains is case-insensitive. Repeat --tag key=value to require multiple tags. --started-after and --started-before accept RFC 3339 timestamps or YYYY-MM-DD dates.

simpcat get run

Show details for a specific run:

simpcat get run a1b2c3d4

simpcat get metric-summary

List metric names, summary stats, and each metric’s latest value, step, and wall time:

simpcat get metric-summary a1b2c3d4

simpcat get metric

View time-series data for a specific metric:

simpcat get metric a1b2c3d4 train/loss

# Limit resolution or filter by step range
simpcat get metric a1b2c3d4 train/loss --resolution bucketed --after-step 100

# Fetch the latest raw point without downloading the full series
simpcat get metric a1b2c3d4 train/loss --last 1 --format json

# Fetch the newest five points inside an exclusive step range
simpcat get metric a1b2c3d4 train/loss --after-step 100 --before-step 1000 --last 5

--last N returns newest points first and defaults to raw resolution so the result is an actual latest point rather than the latest completed rollup bucket.

simpcat get metrics

Query one or more metrics across one or more runs and write the result in machine-readable formats:

simpcat get metrics --runs a1b2c3d4,b5c6d7e8 --metrics train/loss --format csv

simpcat get histogram

Read histogram datapoints for one run and metric:

simpcat get histogram a1b2c3d4 layer/weights
simpcat get histogram a1b2c3d4 layer/weights --after-step 100 --format json
simpcat get histogram a1b2c3d4 layer/weights --format arrow_stream --output weights.arrow

simpcat get files

List signed file URLs for a run:

simpcat get files a1b2c3d4 --format json

simpcat get assets

Query assets across one or more runs:

simpcat get assets --runs a1b2c3d4,b5c6d7e8 --types console_log,image --format json

simpcat export

Export metric data in various formats:

# Export all metrics as Parquet (default)
simpcat export simpcat a1b2c3d4

# Export a specific metric as CSV
simpcat export simpcat a1b2c3d4 train/loss --format csv -o loss.csv

# Export from multiple runs
simpcat export simpcat run1,run2 --format json

Supported formats: parquet, csv, arrow, arrow_stream, json.

Most simpcat get commands support either --format text|json or a machine-oriented export format. For export, use --format json.

simpcat reporter

Internal command — runs the metrics collection reporter for a single run. Called automatically by simpcat.init(), not intended for direct use.

simpcat reporter --run-dir .simpcat/run-xxx/ --run-id abcd1234