CLI

The simpcat CLI is installed automatically with pip install simpcat. It handles authentication, diagnostics, offline run sync, 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.

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

simpcat get run

Show details for a specific run:

simpcat get run a1b2c3d4

simpcat get metric-summary

List metric names and summary stats recorded by a run:

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

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