CLI Reference

Command-Line Help for simpcat

This document contains the help content for the simpcat command-line program.

Command Overview:

• simpcat
• simpcat reporter
• simpcat sync
• simpcat login
• simpcat logout
• simpcat verify
• simpcat get
• simpcat get projects
• simpcat get project
• simpcat get runs
• simpcat get run
• simpcat get metric-summary
• simpcat get metric
• simpcat get histogram
• simpcat get metrics
• simpcat get files
• simpcat get media
• simpcat get assets
• simpcat run
• simpcat run update
• simpcat run delete
• simpcat run tag
• simpcat run tag set
• simpcat run tag rm
• simpcat view
• simpcat view create
• simpcat view list
• simpcat view rename
• simpcat view delete
• simpcat alias
• simpcat alias set
• simpcat alias rm
• simpcat alias list
• simpcat export
• simpcat export simpcat
• simpcat export wandb
• simpcat import
• simpcat import wandb
• simpcat import-job
• simpcat import-job wandb

simpcat

Training metrics platform CLI & reporter

Usage: simpcat <COMMAND>

Subcommands:

• reporter — Run the metrics collection reporter for a single run
• sync — Sync orphaned runs (replay WAL, upload logs, finish)
• login — Authenticate with an API key
• logout — Remove saved API key (for a specific host, or the default key)
• verify — Show configuration and verify server connectivity
• get — Read data from the simpcat public API
• run — Manage runs
• view — Create and manage saved views
• alias — Manage project-level metric name aliases
• export — Export data from simpcat or external platforms
• import — Import runs from external platforms
• import-job — Run a control-plane-managed import job

simpcat reporter

Run the metrics collection reporter for a single run

Usage: simpcat reporter [OPTIONS] --run-dir <RUN_DIR>

Options:

• -d, --run-dir <RUN_DIR> — Path to the run directory (e.g. .simpcat/run-20260219_143052-a1b2c3d4/)
• -r, --run-id <RUN_ID> — Existing canonical run ID for resume. Omit for fresh runs

simpcat sync

Sync orphaned runs (replay WAL, upload logs, finish)

Usage: simpcat sync [OPTIONS] [PATH]

Arguments:

• <PATH> — Path to a specific run directory to sync

Options:

• --all — Scan .simpcat/ or simpcat/ for all unsynced runs

simpcat login

Authenticate with an API key

Usage: simpcat login [OPTIONS]

Options:

• --key <KEY> — API key (prompted if not provided)
• --host <HOST> — Target host (e.g. app.simpcat.ai)

simpcat logout

Remove saved API key (for a specific host, or the default key)

Usage: simpcat logout [OPTIONS]

Options:

• --host <HOST> — Host whose key to remove (e.g. app.simpcat.ai). Removes the default key if omitted

simpcat verify

Show configuration and verify server connectivity

Usage: simpcat verify [OPTIONS]

Options:

• --host <HOST> — Target host (e.g. app.simpcat.ai or sampcat.dev)

simpcat get

Read data from the simpcat public API

Usage: simpcat get <COMMAND>

Subcommands:

• projects — List projects
• project — Show details for a single project
• runs — List runs
• run — Show details for a single run
• metric-summary — Show metric names and summary stats for a run
• metric — Show time-series data for a specific metric
• histogram — Show histogram data for a specific metric
• metrics — Query metric data across one or more runs
• files — List file assets for a run
• media — List media assets for a run
• assets — Query assets across one or more runs

simpcat get projects

List projects

Usage: simpcat get projects [OPTIONS]

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get project

Show details for a single project

Usage: simpcat get project [OPTIONS] <NAME>

Arguments:

• <NAME> — Project name

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get runs

List runs

Usage: simpcat get runs [OPTIONS]

Options:

• --project <PROJECT> — Filter by project name

• --name <NAME> — Filter by exact run name

• --name-contains <NAME_CONTAINS> — Filter by a case-insensitive run-name substring

• --state <STATE> — Filter by derived run state

  Possible values: running, stale, finished, failed, crashed, killed

• --tag <TAGS> — Require a tag in the form key=value (repeat for multiple tags)

• --started-after <STARTED_AFTER> — Only include runs started after this RFC 3339 time or YYYY-MM-DD date

• --started-before <STARTED_BEFORE> — Only include runs started before this RFC 3339 time or YYYY-MM-DD date

• --limit <LIMIT> — Maximum number of runs to return (all runs are returned when omitted)

• --cursor <CURSOR> — Pagination cursor from a previous response

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get run

Show details for a single run

Usage: simpcat get run [OPTIONS] <RUN_ID>

Arguments:

• <RUN_ID> — Run ID

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get metric-summary

Show metric names and summary stats for a run

Usage: simpcat get metric-summary [OPTIONS] <RUN_ID>

Arguments:

• <RUN_ID> — Run ID

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get metric

Show time-series data for a specific metric

Usage: simpcat get metric [OPTIONS] <RUN_ID> <NAME>

Arguments:

• <RUN_ID> — Run ID
• <NAME> — Metric name

Options:

• --resolution <RESOLUTION> — Resolution: auto, raw, or bucketed (default: auto)

• --after-step <AFTER_STEP> — Only return datapoints after this step

• --before-step <BEFORE_STEP> — Only return datapoints before this step

• --limit <LIMIT> — Maximum number of datapoints

• --last <LAST> — Return the newest N datapoints, newest first

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json, csv, parquet, arrow, arrow_stream

• -o, --output <OUTPUT> — Output file path (defaults vary by format)

simpcat get histogram

Show histogram data for a specific metric

Usage: simpcat get histogram [OPTIONS] <RUN_ID> <NAME>

Arguments:

• <RUN_ID> — Run ID
• <NAME> — Histogram metric name

Options:

• --after-step <AFTER_STEP> — Only return datapoints after this step

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json, arrow_stream

• -o, --output <OUTPUT> — Output file path (defaults vary by format)

simpcat get metrics

Query metric data across one or more runs

Usage: simpcat get metrics [OPTIONS] --runs <RUNS>

Options:

• --runs <RUNS> — Comma-separated run IDs

• --metrics <METRICS> — Optional comma-separated metric names

• --resolution <RESOLUTION> — Resolution: raw or bucketed

• --after-step <AFTER_STEP> — Only return datapoints after this step

• --limit <LIMIT> — Maximum number of datapoints

• --format <FORMAT> — Output format

  Default value: json

  Possible values: json, csv, parquet, arrow, arrow_stream

• -o, --output <OUTPUT> — Output file path (defaults vary by format)

simpcat get files

List file assets for a run

Usage: simpcat get files [OPTIONS] <RUN_ID>

Arguments:

• <RUN_ID> — Run ID

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get media

List media assets for a run

Usage: simpcat get media [OPTIONS] <RUN_ID>

Arguments:

• <RUN_ID> — Run ID

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat get assets

Query assets across one or more runs

Usage: simpcat get assets [OPTIONS] --runs <RUNS>

Options:

• --runs <RUNS> — Comma-separated run IDs

• --types <TYPES> — Optional comma-separated asset types

• --after-step <AFTER_STEP> — Only return assets after this step

• --format <FORMAT> — Output format

  Default value: json

  Possible values: text, json

simpcat run

Manage runs

Usage: simpcat run <COMMAND>

Subcommands:

• update — Update a run’s name or notes
• delete — Delete one or more runs
• tag — Manage run tags

simpcat run update

Update a run’s name or notes

Usage: simpcat run update [OPTIONS] <RUN_ID>

Arguments:

• <RUN_ID> — Run ID

Options:

• --name <NAME> — New run name

• --notes <NOTES> — New run notes

• --clear-notes — Clear the run notes

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat run delete

Delete one or more runs

Usage: simpcat run delete [OPTIONS] <RUN_IDS>...

Arguments:

• <RUN_IDS> — Run IDs (maximum 10 per atomic deletion)

Options:

• --execute — Perform the irreversible deletion

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat run tag

Manage run tags

Usage: simpcat run tag <COMMAND>

Subcommands:

• set — Set tags on one or more runs
• rm — Remove tags from one or more runs

simpcat run tag set

Set tags on one or more runs

Usage: simpcat run tag set [OPTIONS] --runs <RUNS> <PAIRS>...

Arguments:

• <PAIRS> — Tags in the form key=value

Options:

• --runs <RUNS> — Comma-separated run IDs (maximum 50 per atomic update)

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat run tag rm

Remove tags from one or more runs

Usage: simpcat run tag rm [OPTIONS] --runs <RUNS> <NAMES>...

Arguments:

• <NAMES> — Tag keys to remove

Options:

• --runs <RUNS> — Comma-separated run IDs (maximum 50 per atomic update)

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat view

Create and manage saved views

Usage: simpcat view <COMMAND>

Subcommands:

• create — Create a saved view containing the specified runs
• list — List saved views
• rename — Rename a saved view
• delete — Delete a saved view

simpcat view create

Create a saved view containing the specified runs

Usage: simpcat view create [OPTIONS] --name <NAME> --runs <RUNS>

Options:

• --name <NAME> — Saved view name

• --runs <RUNS> — Comma-separated canonical run IDs

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat view list

List saved views

Usage: simpcat view list [OPTIONS]

Options:

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat view rename

Rename a saved view

Usage: simpcat view rename [OPTIONS] --name <NAME> <VIEW_ID>

Arguments:

• <VIEW_ID> — Saved view ID

Options:

• --name <NAME> — New saved view name

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat view delete

Delete a saved view

Usage: simpcat view delete [OPTIONS] <VIEW_ID>

Arguments:

• <VIEW_ID> — Saved view ID

Options:

• --execute — Perform the irreversible deletion

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat alias

Manage project-level metric name aliases

Usage: simpcat alias <COMMAND>

Subcommands:

• set — Set alias mappings: simpcat alias set val_loss=validation/loss –project my-proj
• rm — Remove aliases by alternate name
• list — List aliases for a project

simpcat alias set

Set alias mappings: simpcat alias set val_loss=validation/loss –project my-proj

Usage: simpcat alias set [OPTIONS] --project <PROJECT> <PAIRS>...

Arguments:

• <PAIRS> — Mappings in the form alternate=canonical

Options:

• --project <PROJECT> — Project name

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat alias rm

Remove aliases by alternate name

Usage: simpcat alias rm [OPTIONS] --project <PROJECT> <NAMES>...

Arguments:

• <NAMES> — Alternate names to remove

Options:

• --project <PROJECT> — Project name

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat alias list

List aliases for a project

Usage: simpcat alias list [OPTIONS] --project <PROJECT>

Options:

• --project <PROJECT> — Project name

• --format <FORMAT> — Output format

  Default value: text

  Possible values: text, json

simpcat export

Export data from simpcat or external platforms

Usage: simpcat export <COMMAND>

Subcommands:

• simpcat — Export metric data from simpcat in various formats
• wandb — Export runs from Weights & Biases via GraphQL API

simpcat export simpcat

Export metric data from simpcat in various formats

Usage: simpcat export simpcat [OPTIONS] <RUN_ID> [METRIC]

Arguments:

• <RUN_ID> — Run ID (or comma-separated run IDs)
• <METRIC> — Metric name (optional — exports all metrics if omitted)

Options:

• --format <FORMAT> — Output format: parquet, csv, arrow, arrow_stream, json

  Default value: parquet

• -o, --output <OUTPUT> — Output file path (default: stdout for csv/json, or metrics_export.)

simpcat export wandb

Export runs from Weights & Biases via GraphQL API

Usage: simpcat export wandb [OPTIONS] --entity <ENTITY> --project <PROJECT>

Options:

• --entity <ENTITY> — W&B entity (user or team name)

• --project <PROJECT> — W&B project name

• --output <OUTPUT> — Output directory (default: ./wandb-export)

  Default value: ./wandb-export

• --api-key <API_KEY> — W&B API key (overrides WANDB_API_KEY env and ~/.netrc)

• --base-url <BASE_URL> — W&B API base URL

  Default value: https://api.wandb.ai

• --concurrency <CONCURRENCY> — Max concurrent downloads

  Default value: 10

• --started-after <STARTED_AFTER> — Only export runs started after this date (ISO 8601 or relative: 90d, 3months, 1y)

• --limit <LIMIT> — Max number of runs to export

• --include-media — Include media files (images, audio, etc.)

• --run <RUN> — Export a single run by W&B run ID

• --execute — Actually perform the export (default is dry-run preview)

simpcat import

Import runs from external platforms

Usage: simpcat import <COMMAND>

Subcommands:

• wandb — Import runs from a Weights & Biases export directory

simpcat import wandb

Import runs from a Weights & Biases export directory

Usage: simpcat import wandb [OPTIONS] <SOURCE_DIR>

Arguments:

• <SOURCE_DIR> — Path to W&B export directory (///)

Options:

• --host <HOST> — Target host (default: from config)

• --api-key <API_KEY> — API key (overrides config file)

• --concurrency <CONCURRENCY> — Max concurrent requests

  Default value: 20

• --project <PROJECT> — Filter to a single project

• --run <RUN> — Filter to a single W&B run ID

• --sample <SAMPLE> — Sample N runs (evenly spaced)

• --dry-run — Dry run: scan and summarize without making network calls

• --inspect — Inspect: show parquet schema, sample TSV, and API payloads

• --estimate — Estimate storage and ingestion time from samples

• --limit <LIMIT> — Max runs to inspect (only with –inspect)

  Default value: 5

• --direct — Insert metrics directly into ClickHouse (requires CH env vars)

• --timeout <TIMEOUT> — HTTP timeout in seconds (default: 30 for CF Worker, 300 for ClickHouse)

• --started-after <STARTED_AFTER> — Only import runs started after this date (ISO 8601 e.g. 2025-01-15, or relative: 90d, 3months, 1y)

simpcat import-job

Run a control-plane-managed import job

Usage: simpcat import-job <COMMAND>

Subcommands:

• wandb — Execute a W&B import job claimed from the simpcat control plane

simpcat import-job wandb

Execute a W&B import job claimed from the simpcat control plane

Usage: simpcat import-job wandb --host <HOST> --job-id <JOB_ID>

Options:

• --host <HOST> — Base URL for the Convex control plane host (e.g. https://…convex.site)
• --job-id <JOB_ID> — Import job ID from the W&B import control plane

---

This document was generated automatically by clap-markdown.