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, Train and test a checkpoint, or Define your agent. For scripts, consult 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 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

synth run flags

synth run [command]

Flag	Value	Meaning
--help / -h	boolean	help for run
--config-dir	string	Override the Synth config directory

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

claude

Launch Claude Code through Synth.

Command	Purpose
synth claude	Launch Claude Code through Synth

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

synth completion flags

synth completion [command]

Flag	Value	Meaning
--help / -h	boolean	help for completion
--config-dir	string	Override the Synth config directory

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

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

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

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

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

synth config flags

synth config [command]

Flag	Value	Meaning
--help / -h	boolean	help for config
--config-dir	string	Override the Synth config directory

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

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

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

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

login

Sign in to SynthLabs.

Command	Purpose
synth login	Sign in to SynthLabs

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

logout

Remove locally stored Synth credentials.

Command	Purpose
synth logout	Remove locally stored Synth credentials

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

status

Show user authentication and local request credential readiness.

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

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

version

Print version information.

Command	Purpose
synth version	Print version information

synth version flags

synth version [flags]

Flag	Value	Meaning
--help / -h	boolean	help for version
--config-dir	string	Override the Synth config directory

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

synth workspace flags

synth workspace [command]

Flag	Value	Meaning
--help / -h	boolean	help for workspace
--config-dir	string	Override the Synth config directory

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

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

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

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

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

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

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

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