> ## Documentation Index
> Fetch the complete documentation index at: https://synthlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Release-linked command and flag reference for the Synth CLI.

This reference is generated from the released **0.0.1-alpha.62** executable. It describes command syntax, not a guarantee of account access, model availability or a successful remote execution.

For a guided path, start with [Run an agent](/guides/managed-execution), [Train and test a checkpoint](/guides/managed-training), or [Define your agent](/concepts/profiles-and-candidates). For scripts, consult [Automation](/integrations/automation) and the command's documented JSON behavior.

Use the full command or version reference printed by a preceding command. Examples using `acme` or angle brackets require your own namespace or identifier. See [installation](/getting-started/install) if your executable predates this reference. Native Claude arguments belong to the native tool, not this parser.

## run

Run agents and inspect execution, results and evidence.

| Command | Purpose |
| - | - |
| `synth run` | Run agents and inspect execution, results and evidence |
| `synth run artifacts` | List the run's artifact and checkpoint refs |
| `synth run artifacts download` | Download and verify one finalized run artifact |
| `synth run cancel` | Cancel a managed run |
| `synth run capture` | Download one completed historical native review with verified custody |
| `synth run checkpoints` | List saved model checkpoints |
| `synth run events` | Read the run's canonical event timeline |
| `synth run export` | Export complete, verified terminal run evidence |
| `synth run groups` | List sampling or training groups |
| `synth run list` | List managed runs across execution, evaluation and training |
| `synth run regrade` | Score a finished run's retained actor outputs with a different judge |
| `synth run result` | Get the canonical terminal managed-run result |
| `synth run show` | Show the run's managed lifecycle hierarchy |
| `synth run start` | Run an agent on a dataset or a single task |
| `synth run trials` | List trials and their task outcomes and rewards |
| `synth run updates` | List model updates and saved checkpoints |

<AccordionGroup>
  <Accordion title="synth run flags">
    `synth run [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for run |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run artifacts flags">
    `synth run artifacts <run-uuid> [flags] / synth run artifacts [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for artifacts |
    | `--json` | boolean | Print stable JSON output |
    | `--role` | string | Filter by recorded actor/reviewer or judge role |
    | `--role-execution` | string | Filter by recorded role execution UUID |
    | `--trial` | string | Filter by recorded trial UUID; excludes legacy unknown associations |
    | `--wide` | boolean | Include artifact identifiers and locations |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run artifacts download flags">
    `synth run artifacts download <run-uuid> <artifact-name-or-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for download |
    | `--output` / `-o` | string | Destination file (must not already exist) |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run cancel flags">
    `synth run cancel <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for cancel |
    | `--json` | boolean | Print stable JSON output |
    | `--yes` | boolean | Confirm cancellation |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run capture flags">
    `synth run capture <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for capture |
    | `--output` / `-o` | string | New destination directory for submission.json and receipt.json |
    | `--role` | string | Reviewer role UUID (optional for a single-review run) |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run checkpoints flags">
    `synth run checkpoints <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--attempt` | string | Read one attempt of the run: its number (1, 2, ...) or UUID |
    | `--help` / `-h` | boolean | help for checkpoints |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum items to return (1-200) (default 20) |
    | `--offset` | int | Number of ordered items to skip |
    | `--wide` | boolean | Show full stable IDs |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run events flags">
    `synth run events <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--follow` | boolean | Poll until the run reaches a terminal state |
    | `--help` / `-h` | boolean | help for events |
    | `--json` | boolean | Print stable JSON output (one event per line with --follow) |
    | `--jsonl` | boolean | Print one stable JSON event per line (pagination metadata omitted) |
    | `--limit` | int | Maximum canonical events to examine (default 50) |
    | `--offset` | int | Zero-based canonical event offset |
    | `--timeout` | duration | Maximum follow duration; 0 waits until terminal |
    | `--verbose` | boolean | Include group starts and trial events |
    | `--wide` | boolean | Expand selected event details |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run export flags">
    `synth run export <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for export |
    | `--output` / `-o` | string | New destination directory |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run groups flags">
    `synth run groups <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--attempt` | string | Read one attempt of the run: its number (1, 2, ...) or UUID |
    | `--help` / `-h` | boolean | help for groups |
    | `--json` | boolean | Print stable JSON output |
    | `--kind` | string | Group kind: sampling or training (default "sampling") |
    | `--limit` | int | Maximum items to return (1-200) (default 20) |
    | `--offset` | int | Number of ordered items to skip |
    | `--wide` | boolean | Show full stable IDs |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run list flags">
    `synth run list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--dataset` | string | Keep only runs whose dataset reference contains this text |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print stable JSON output |
    | `--kind` | string | Filter: execution, evaluation or training |
    | `--limit` | int | Maximum runs to return (1-200) (default 20) |
    | `--offset` | int | Number of newest runs to skip |
    | `--state` | string | Keep only runs in this state: pending, queued, preparing, running, cancelling, succeeded, failed, cancelled |
    | `--wide` | boolean | Show full customer model names and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run regrade flags">
    `synth run regrade <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--dry-run` | boolean | Print the derived tasks and the exact request Synth would receive; downloads the retained archives to read them, uploads nothing and launches nothing |
    | `--help` / `-h` | boolean | help for regrade |
    | `--idempotency-key` | string | Optional replay key; when omitted, synth generates a unique key for this submission |
    | `--json` | boolean | Print stable JSON output |
    | `--judge` | string | Judge agent profile that scores the retained outputs: agent://namespace/name\@version or @profile.json (required). It writes a finite "reward" to /logs/verifier/reward.json, the only key scored; any other key it writes there (rationale, criteria, citations) is retained and ignored |
    | `--plan` | string | Run plan as one JSON object, or @file (default \{"trials\_per\_task":1}) |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run result flags">
    `synth run result <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for result |
    | `--json` | boolean | Print stable JSON output |
    | `--wide` | boolean | Include stable evidence identifiers and digests |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run show flags">
    `synth run show <run-or-child-ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--attempt` | string | Show one attempt (number 1, 2, ... or UUID), or read --group/--trial from it |
    | `--group` | string | Show one exact sampling-group UUID within the run |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print stable JSON output |
    | `--trial` | string | Show one exact trial UUID within the run |
    | `--wide` | boolean | Show full stable IDs |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run start flags">
    `synth run start [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--actor` | string | Actor agent profile: agent://namespace/name\@version or @profile.json (default: the platform's default actor) |
    | `--dataset` / `-d` | string | One dataset ref; Synth resolves and pins it as the run task set |
    | `--dry-run` | boolean | Explain the planned work and what was and was not checked, without publishing or launching (with --json: the exact dataset request or task launch plan); task and agent:// references are resolved read-only |
    | `--help` / `-h` | boolean | help for start |
    | `--idempotency-key` | string | Optional replay key; when omitted, synth generates a unique key for this submission |
    | `--json` | boolean | Print stable JSON output |
    | `--judge` | string | Judge agent profile that replaces the task's verifier: it writes a finite "reward" to /logs/verifier/reward.json, the only key scored; any other key it writes there (rationale, criteria, citations) is retained and ignored. Omit to score with the task's own verifier |
    | `--no-judge` | boolean | Collect unscored executions: no verifier, no judge, no reward |
    | `--plan` | string | Run plan as one JSON object, or @file (default \{"trials\_per\_task":1}) |
    | `--task` | string | One task ref to run on its own; synth reuses or creates a private one-task dataset for it |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run trials flags">
    `synth run trials <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--attempt` | string | Read one attempt of the run: its number (1, 2, ...) or UUID |
    | `--group` | string | Restrict to one sampling-group UUID |
    | `--help` / `-h` | boolean | help for trials |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum items to return (1-200) (default 20) |
    | `--offset` | int | Number of ordered items to skip |
    | `--wide` | boolean | Show full stable IDs |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth run updates flags">
    `synth run updates <run-uuid> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--attempt` | string | Read one attempt of the run: its number (1, 2, ...) or UUID |
    | `--help` / `-h` | boolean | help for updates |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum items to return (1-200) (default 20) |
    | `--offset` | int | Number of ordered items to skip |
    | `--wide` | boolean | Show full stable IDs |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## train

Start Synth-managed training runs.

| Command | Purpose |
| - | - |
| `synth train` | Start Synth-managed training runs |
| `synth train start` | Train an actor agent on a dataset or a single task with an explicit plan |

<AccordionGroup>
  <Accordion title="synth train flags">
    `synth train [flags] / synth train [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for train |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth train start flags">
    `synth train start [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--actor` | string | Actor agent profile: agent://namespace/name\@version or @profile.json (default: the platform's default actor) |
    | `--dataset` / `-d` | string | One dataset ref; Synth resolves and pins it as the run task set |
    | `--dry-run` | boolean | Explain the planned work and what was and was not checked, without publishing or launching (with --json: the exact dataset request or task launch plan); task and agent:// references are resolved read-only |
    | `--help` / `-h` | boolean | help for start |
    | `--idempotency-key` | string | Optional replay key; when omitted, synth generates a unique key for this submission |
    | `--json` | boolean | Print stable JSON output |
    | `--judge` | string | Judge agent profile that replaces the task's verifier: it writes a finite "reward" to /logs/verifier/reward.json, the only key scored; any other key it writes there (rationale, criteria, citations) is retained and ignored. Omit to score with the task's own verifier |
    | `--plan` | string | Training plan as one JSON object, or @file (required) |
    | `--task` | string | One task ref to run on its own; synth reuses or creates a private one-task dataset for it |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## agent

Publish and inspect versioned native agent profiles.

| Command | Purpose |
| - | - |
| `synth agent` | Publish and inspect versioned native agent profiles |
| `synth agent create` | Publish an immutable profile; existing names require the current version UUID |
| `synth agent list` | List visible agent profiles |
| `synth agent run` | Prepare and run an exact agent recipe locally (not a sandbox) |
| `synth agent show` | Resolve a profile and verify its exact immutable content |
| `synth agent validate` | Check a credential-free profile locally, without login or execution |
| `synth agent versions` | List immutable agent versions |

<AccordionGroup>
  <Accordion title="synth agent flags">
    `synth agent [flags] / synth agent [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for agent |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent create flags">
    `synth agent create <namespace/name> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--description` | string | Short profile description |
    | `--expected-current-version` | string | Required current UUID when publishing a new version of an existing name |
    | `--help` / `-h` | boolean | help for create |
    | `--idempotency-key` | string | Replay key for this exact publication |
    | `--json` | boolean | Print the immutable publication receipt |
    | `--profile` | string | Path to the checked agent-profile JSON |
    | `--visibility` | string | Profile visibility: private or org (default "private") |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent list flags">
    `synth agent list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print profile page JSON |
    | `--limit` | int | Maximum entries (1–100) (default 20) |
    | `--offset` | int | Entries to skip |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent run flags">
    `synth agent run <agent-reference|@profile.json> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--bindings` | string | Execution bindings JSON; values do not grant access |
    | `--dry-run` | boolean | Resolve and print the launch without setup, installation or inference; an @profile.json stays offline, an agent:// reference is still read from Synth |
    | `--help` / `-h` | boolean | help for run |
    | `--phase` | string | Execution phase: all, setup or run (run requires matching setup) (default "all") |
    | `--receipt` | string | Write a redacted launch receipt to this file |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent show flags">
    `synth agent show <agent://namespace/name[@version]> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print version, canonical profile and identity JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent validate flags">
    `synth agent validate <profile.json> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for validate |
    | `--json` | boolean | Print checked profile JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth agent versions flags">
    `synth agent versions <agent://namespace/name> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for versions |
    | `--json` | boolean | Print version page JSON |
    | `--limit` | int | Maximum entries (1–100) (default 20) |
    | `--offset` | int | Entries to skip |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## dataset

Create and manage datasets.

| Command | Purpose |
| - | - |
| `synth dataset` | Create and manage datasets |
| `synth dataset create` | Create a new immutable ordered dataset version |
| `synth dataset download` | Download every ordered task occurrence in a dataset |
| `synth dataset list` | List your datasets |
| `synth dataset runs` | List evaluation and training runs that used a dataset |
| `synth dataset show` | Show dataset metadata and version history |
| `synth dataset tasks` | List the ordered task versions in a dataset |

<AccordionGroup>
  <Accordion title="synth dataset flags">
    `synth dataset [flags] / synth dataset [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for dataset |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset create flags">
    `synth dataset create <name> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--dry-run` | boolean | Show what would be created without creating it |
    | `--from` | string | YAML file listing uploaded task versions |
    | `--help` / `-h` | boolean | help for create |
    | `--json` | boolean | Print machine-readable JSON output |
    | `--task` | stringArray | Exact task\@vN to include; repeat in dataset order |
    | `--visibility` | string | Visibility (private, organization, public) (default "private") |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset download flags">
    `synth dataset download <dataset[@vN]> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for download |
    | `--json` | boolean | Print stable JSON output |
    | `--output` / `-o` | string | New directory for the ordered dataset tasks |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset list flags">
    `synth dataset list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all-accessible` | boolean | Include public packages owned by other users |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-100) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--query` / `-q` | string | Search names and descriptions |
    | `--source` | string | Filter by source (synth, harbor); harbor includes the public catalog |
    | `--visibility` | string | Filter by visibility (private, organization, public) |
    | `--wide` | boolean | Print full package references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset runs flags">
    `synth dataset runs <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all-versions` | boolean | Include runs from every version of this dataset |
    | `--help` / `-h` | boolean | help for runs |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum runs to return (1-100) (default 20) |
    | `--offset` | int | Number of rows to skip |
    | `--operation` | string | Filter runs by eval or train |
    | `--wide` | boolean | Print full references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset show flags">
    `synth dataset show <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum versions to return (1-200) (default 20) |
    | `--offset` | int | Number of rows to skip |
    | `--wide` | boolean | Print full references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth dataset tasks flags">
    `synth dataset tasks <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for tasks |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum tasks to return (1-1000) (default 20) |
    | `--offset` | int | Number of rows to skip |
    | `--wide` | boolean | Print full references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## task

Upload and manage tasks.

| Command | Purpose |
| - | - |
| `synth task` | Upload and manage tasks |
| `synth task author` | Create a task from session feedback or modify an existing task |
| `synth task author cancel` | Cancel authoring and drain its active execution |
| `synth task author show` | Inspect authoring progress, tasks, and evidence |
| `synth task author wait` | Wait for the terminal authoring result and its validation evidence |
| `synth task download` | Download one task version or an ordered list into new task directories |
| `synth task groups` | List recorded sampling groups for a task |
| `synth task install-claude-command` | Install the /task session-feedback command for Synth Claude |
| `synth task list` | List your tasks |
| `synth task result` | Inspect a legacy task execution through its immutable version |
| `synth task retry` | Retry an exact retained /task capture |
| `synth task show` | Show one task and its resolved current or exact version |
| `synth task trials` | List recorded trials for a task |
| `synth task upload` | Upload one task directory or a manifest of local tasks |

<AccordionGroup>
  <Accordion title="synth task flags">
    `synth task [flags] / synth task [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for task |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task author flags">
    `synth task author [flags] / synth task author [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--context` | stringArray | Immutable context artifact ref, visible only to the author (repeatable) |
    | `--deadline` | duration | Overall run deadline, including evaluation and revision (default 1h0m0s) |
    | `--dry-run` | boolean | Package and preview a program request without login or network calls |
    | `--feedback` | string | Your correction or description of what went wrong |
    | `--help` / `-h` | boolean | help for author |
    | `--instructions` | string | Requested changes to the task |
    | `--json` | boolean | Print the stable run contract, including preserved evidence |
    | `--max-attempts` | int | Maximum candidate authoring attempts (default 3) |
    | `--preserve` | stringArray | Additional constraint the modification must preserve (repeatable) |
    | `--preserve-path` | stringArray | Relative task file that must remain unchanged (repeatable) |
    | `--program` | string | Task-production program (modify-task\@1) |
    | `--request-id` | string | Stable retry identity (generated when omitted) |
    | `--runtime-auth-profile` | string | Use an existing runtime auth profile UUID |
    | `--session` | string | Attach an existing Cloud session UUID |
    | `--session-file` | string | Upload a local normalized or native Claude JSONL session |
    | `--target-event` | string | Assistant event ID at the failure boundary |
    | `--task` | string | Existing Harbor task directory or immutable task reference |
    | `--timeout` | duration | Local wait limit (defaults to --deadline plus 2m); stopping the wait leaves the run active (default 1h2m0s) |
    | `--upload` | string | Attach a finalized session ingestion UUID |
    | `--wait` | boolean | Wait for the terminal result |
    | `--workspace` | string | Capture tracked files from this Git repository root |
    | `--workspace-ref` | string | Use an owned immutable workspace artifact reference |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task author cancel flags">
    `synth task author cancel <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for cancel |
    | `--json` | boolean | Print the stable run contract, including preserved evidence |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task author show flags">
    `synth task author show <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print the stable run contract, including preserved evidence |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task author wait flags">
    `synth task author wait <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for wait |
    | `--json` | boolean | Print the stable run contract, including preserved evidence |
    | `--timeout` | duration | How long to wait locally (default covers the maximum run deadline plus 2m) (default 4h2m0s) |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task download flags">
    `synth task download [task[@vN]] [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--archive` | boolean | Keep the verified raw task archive instead of unpacking it |
    | `--from` | string | YAML file listing exact task\@vN references |
    | `--help` / `-h` | boolean | help for download |
    | `--json` | boolean | Print stable JSON output |
    | `--output` / `-o` | string | New task directory, or archive path with --archive |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task groups flags">
    `synth task groups <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all-versions` | boolean | Include recorded rows from every task version |
    | `--help` / `-h` | boolean | help for groups |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum groups to return (1-100) (default 20) |
    | `--links` | boolean | Print copyable exact-ID navigation commands |
    | `--offset` | int | Number of rows to skip |
    | `--operation` | string | Filter by eval or train |
    | `--wide` | boolean | Print full references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task install-claude-command flags">
    `synth task install-claude-command [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for install-claude-command |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task list flags">
    `synth task list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all-accessible` | boolean | Include public packages owned by other users |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-100) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--query` / `-q` | string | Search names and descriptions |
    | `--source` | string | Filter by source (synth, harbor); harbor includes the public catalog |
    | `--visibility` | string | Filter by visibility (private, organization, public) |
    | `--wide` | boolean | Print full package references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task result flags">
    `synth task result <exact-task-ref> <execution-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for result |
    | `--json` | boolean | Output pinned execution and result JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task retry flags">
    `synth task retry <request-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for retry |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task show flags">
    `synth task show <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum version history rows to return (1-200) (default 50) |
    | `--offset` | int | Number of newest versions to skip |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task trials flags">
    `synth task trials <ref> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all-versions` | boolean | Include recorded rows from every task version |
    | `--group` | string | Filter by a canonical sampling-group UUID |
    | `--help` / `-h` | boolean | help for trials |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum trials to return (1-100) (default 20) |
    | `--links` | boolean | Print copyable exact-ID navigation commands |
    | `--offset` | int | Number of rows to skip |
    | `--operation` | string | Filter by eval or train |
    | `--wide` | boolean | Print full references and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth task upload flags">
    `synth task upload [task-directory] [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--dry-run` | boolean | Package and inspect the task without uploading it |
    | `--from` | string | YAML file listing local task folders |
    | `--help` / `-h` | boolean | help for upload |
    | `--json` | boolean | Print stable JSON output |
    | `--name` | string | Task name (defaults to the directory name) |
    | `--visibility` | string | Visibility (private, organization, public) (default "private") |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## checkpoint

Browse saved checkpoints and their actual use.

| Command | Purpose |
| - | - |
| `synth checkpoint` | Browse saved checkpoints and their actual use |
| `synth checkpoint children` | List direct descendant checkpoints that were actually saved |
| `synth checkpoint groups` | List sampling groups that actually used this checkpoint |
| `synth checkpoint list` | List your saved checkpoints newest first |
| `synth checkpoint runs` | List the source and downstream runs related to this checkpoint |
| `synth checkpoint show` | Show one checkpoint, its training progress, source, and parent |

<AccordionGroup>
  <Accordion title="synth checkpoint flags">
    `synth checkpoint [flags] / synth checkpoint [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for checkpoint |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth checkpoint children flags">
    `synth checkpoint children <checkpoint-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for children |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-200) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth checkpoint groups flags">
    `synth checkpoint groups <checkpoint-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for groups |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-200) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--operation` | string | Filter by operation: eval or train |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth checkpoint list flags">
    `synth checkpoint list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-200) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth checkpoint runs flags">
    `synth checkpoint runs <checkpoint-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for runs |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum records to return (1-200) (default 20) |
    | `--offset` | int | Number of records to skip |
    | `--operation` | string | Filter by operation: eval or train |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth checkpoint show flags">
    `synth checkpoint show <checkpoint-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print stable JSON output |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## session

Browse, back up, and export coding sessions.

| Command | Purpose |
| - | - |
| `synth session` | Browse, back up, and export coding sessions |
| `synth session backup` | Back up local coding sessions to your Synth account |
| `synth session export` | Download and verify Session Interaction evidence |
| `synth session import` | Publish a reviewed normalized session file to Sessions |
| `synth session interactions` | List the Session's interactions newest first |
| `synth session list` | List Claude Code Sessions newest first |
| `synth session show` | Show one Session overview and its origin |
| `synth session streams` | List the Session's agent streams by last request |

<AccordionGroup>
  <Accordion title="synth session flags">
    `synth session [flags] / synth session [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for session |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session backup flags">
    `synth session backup [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all` | boolean | Include all local sessions (required for upload alias) |
    | `--configuration-evidence` | boolean | Preserve nonportable Claude authored files as inert private evidence; cannot make environments runnable |
    | `--dry-run` | boolean | Estimate native transcript/database coverage without uploading |
    | `--help` / `-h` | boolean | help for backup |
    | `--json` | boolean | Print structured discovery or backup results |
    | `--recent` | int | Upload N newest sessions plus linked agent threads (1–100); save conversations first, then populate their environments |
    | `--recent-first` | int | Experimental: save N newest sessions plus linked agent threads first (1–100), then back up all sessions |
    | `--setup-attempt` | string | Connect this recent upload to the setup attempt shown in your browser |
    | `--verbose` | boolean | Show per-source capture and indexing diagnostics |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session export flags">
    `synth session export <session_id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for export |
    | `--json` | boolean | Print stable JSON output |
    | `--output` | string | Install evidence in a new directory |
    | `--stream` | string | Restrict export to one canonical stream UUID |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session import flags">
    `synth session import [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--dry-run` | boolean | Validate locally without uploading content |
    | `--file` | string | Reviewed normalized JSONL file (maximum 4 MiB) |
    | `--help` / `-h` | boolean | help for import |
    | `--json` | boolean | Print canonical Session IDs and publication status |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session interactions flags">
    `synth session interactions <session_id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for interactions |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum interactions to return (1-100) (default 20) |
    | `--offset` | int | Number of interactions to skip |
    | `--stream` | string | Restrict to one canonical stream UUID |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session list flags">
    `synth session list [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--all` | boolean | Write all pages to --output |
    | `--catalog` | boolean | Browse Sessions across capture sources |
    | `--cursor` | string | Opaque continuation cursor |
    | `--help` / `-h` | boolean | help for list |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Sessions per page (default 20) |
    | `--offset` | int | Number of newest Sessions to skip |
    | `--output` | string | Write stable JSON to a new file |
    | `--project` | string | Filter catalog by project ID |
    | `--search` | string | Search catalog titles and previews |
    | `--source` | string | Filter catalog by source kind |
    | `--wide` | boolean | Show exact request timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session show flags">
    `synth session show <session_id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--catalog` | boolean | Read a canonical cross-source conversation |
    | `--help` / `-h` | boolean | help for show |
    | `--json` | boolean | Print stable JSON output |
    | `--message-cursor` | string | Opaque conversation continuation cursor |
    | `--message-limit` | int | Conversation messages per page (default 100) |
    | `--whole-messages` | boolean | Read complete messages within the service size limit |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth session streams flags">
    `synth session streams <session_id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for streams |
    | `--json` | boolean | Print stable JSON output |
    | `--limit` | int | Maximum streams to return (1-100) (default 20) |
    | `--offset` | int | Number of streams to skip |
    | `--wide` | boolean | Show full IDs and exact timestamps |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## claude

Launch Claude Code through Synth.

| Command | Purpose |
| - | - |
| `synth claude` | Launch Claude Code through Synth |

<AccordionGroup />

## completion

Generate the autocompletion script for the specified shell.

| Command | Purpose |
| - | - |
| `synth completion` | Generate the autocompletion script for the specified shell |
| `synth completion bash` | Generate the autocompletion script for bash |
| `synth completion fish` | Generate the autocompletion script for fish |
| `synth completion powershell` | Generate the autocompletion script for powershell |
| `synth completion zsh` | Generate the autocompletion script for zsh |

<AccordionGroup>
  <Accordion title="synth completion flags">
    `synth completion [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for completion |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth completion bash flags">
    `synth completion bash`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for bash |
    | `--no-descriptions` | boolean | disable completion descriptions |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth completion fish flags">
    `synth completion fish [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for fish |
    | `--no-descriptions` | boolean | disable completion descriptions |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth completion powershell flags">
    `synth completion powershell [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for powershell |
    | `--no-descriptions` | boolean | disable completion descriptions |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth completion zsh flags">
    `synth completion zsh [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for zsh |
    | `--no-descriptions` | boolean | disable completion descriptions |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## config

Manage configuration settings.

| Command | Purpose |
| - | - |
| `synth config` | Manage configuration settings |
| `synth config get` | Get a configuration value |
| `synth config set` | Set a configuration value |
| `synth config show` | View all configuration settings |
| `synth config unset` | Reset a configuration value to default |

<AccordionGroup>
  <Accordion title="synth config flags">
    `synth config [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for config |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth config get flags">
    `synth config get <key> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for get |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth config set flags">
    `synth config set <key> <value> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for set |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth config show flags">
    `synth config show [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for show |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth config unset flags">
    `synth config unset <key> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for unset |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## login

Sign in to SynthLabs.

| Command | Purpose |
| - | - |
| `synth login` | Sign in to SynthLabs |

<AccordionGroup>
  <Accordion title="synth login flags">
    `synth login [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for login |
    | `--json` | boolean | Output the fixed receipt as JSON |
    | `--no-browser` | boolean | Print the verification URL and code instead of opening a browser |
    | `--reauthenticate` | boolean | Restart device authorization and refresh the current user's cached credential |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## logout

Remove locally stored Synth credentials.

| Command | Purpose |
| - | - |
| `synth logout` | Remove locally stored Synth credentials |

<AccordionGroup>
  <Accordion title="synth logout flags">
    `synth logout [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for logout |
    | `--json` | boolean | Output the fixed receipt as JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## status

Show user authentication and local request credential readiness.

| Command | Purpose |
| - | - |
| `synth status` | Show user authentication and local request credential readiness |

<AccordionGroup>
  <Accordion title="synth status flags">
    `synth status [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for status |
    | `--json` | boolean | Output stable status JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## version

Print version information.

| Command | Purpose |
| - | - |
| `synth version` | Print version information |

<AccordionGroup>
  <Accordion title="synth version flags">
    `synth version [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for version |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>
</AccordionGroup>

## workspace

Use prepared workspaces and saved setup.

| Command | Purpose |
| - | - |
| `synth workspace` | Use prepared workspaces and saved setup |
| `synth workspace attach` | Reconnect to the exact retained terminal attempt |
| `synth workspace exec` | Open an interactive command in a prepared workspace |
| `synth workspace setup` | Inspect or replay a saved setup recipe |
| `synth workspace setup cancel` | Request cancellation of a setup Run |
| `synth workspace setup events` | Read one page of setup Run events |
| `synth workspace setup get` | Show setup eligibility and verified recipe proof |
| `synth workspace setup replay` | Replay an exact saved recipe once |
| `synth workspace setup status` | Show setup Run execution state |

<AccordionGroup>
  <Accordion title="synth workspace flags">
    `synth workspace [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for workspace |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth workspace attach flags">
    `synth workspace attach <state-file> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for attach |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth workspace exec flags">
    `synth workspace exec <environment-id> <command> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--columns` | int | Initial terminal columns (detected by default) |
    | `--help` / `-h` | boolean | help for exec |
    | `--lookup` | boolean | Only reconcile the original command admission |
    | `--request-id` | string | Admission UUID (generated by default) |
    | `--rows` | int | Initial terminal rows (detected by default) |
    | `--state-file` | string | Private reconnect state file (saved under Synth config by default) |
    | `--timeout` | int | Terminal lifetime in seconds, at most 3600 (default 3600) |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth workspace setup flags">
    `synth workspace setup [command]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for setup |
    | `--json` | boolean | Print machine-readable JSON |
    | `--config-dir` | string | Override the Synth config directory |
  </Accordion>

  <Accordion title="synth workspace setup cancel flags">
    `synth workspace setup cancel <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for cancel |
    | `--config-dir` | string | Override the Synth config directory |
    | `--json` | boolean | Print machine-readable JSON |
  </Accordion>

  <Accordion title="synth workspace setup events flags">
    `synth workspace setup events <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--after` | string | Resume after this cursor; prints one page without polling |
    | `--help` / `-h` | boolean | help for events |
    | `--config-dir` | string | Override the Synth config directory |
    | `--json` | boolean | Print machine-readable JSON |
  </Accordion>

  <Accordion title="synth workspace setup get flags">
    `synth workspace setup get <environment-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for get |
    | `--run-id` | string | Read proof for this setup Run |
    | `--config-dir` | string | Override the Synth config directory |
    | `--json` | boolean | Print machine-readable JSON |
  </Accordion>

  <Accordion title="synth workspace setup replay flags">
    `synth workspace setup replay <environment-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for replay |
    | `--lookup` | boolean | Read existing admission only; never submit or retry |
    | `--recipe-run-id` | string | Run that produced the saved recipe (required) |
    | `--recipe-sha256` | string | Exact saved recipe SHA256 (required) |
    | `--request-id` | string | Stable UUID for this replay intent (required) |
    | `--config-dir` | string | Override the Synth config directory |
    | `--json` | boolean | Print machine-readable JSON |
  </Accordion>

  <Accordion title="synth workspace setup status flags">
    `synth workspace setup status <run-id> [flags]`

    | Flag | Value | Meaning |
    | - | - | - |
    | `--help` / `-h` | boolean | help for status |
    | `--config-dir` | string | Override the Synth config directory |
    | `--json` | boolean | Print machine-readable JSON |
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.