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 metrics
• simpcat get files
• simpcat get media
• simpcat get assets
• 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
• 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
• 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

• --limit <LIMIT> — Maximum number of runs to return

  Default value: 100

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

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

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