Docs/Reference

CLI reference

The syn command line tool develops, deploys and operates Synchronoid projects. This page lists every command and its flags. To install it, see Install the CLI.

Commands at a glance

Command	Purpose
`syn login`	Sign in and store a token.
`syn init`	Create a new project.
`syn dev`	Run your project locally with live reload.
`syn deploy`	Upload the project to a workspace.
`syn runs list`	List runs.
`syn runs show`	Show the steps and logs of one run.
`syn runs replay`	Replay a run from stored data.
`syn runs cancel`	Cancel a running run.
`syn sources`	List, inspect, pause and resume sources.
`syn backfill`	Run an asset for past partitions.
`syn secrets`	Manage secrets.
`syn feeds`	Manage change feed subscriptions.
`syn alerts`	Test and list alert rules and channels.
`syn materialize`	Run an asset once, optionally from raw data and with downstream assets.
`syn schedules`, `syn sensors`	List and disable schedules, test sensors.
`syn connector test`	Test a custom connector against a fixture file.
`syn completion`	Print shell completion for bash, zsh or fish.
`syn doctor`	Check your setup and collect diagnostics.

Global flags

Flag	Description
`--workspace NAME`	Workspace to use. Default: the one in `synchronoid.yaml` or the last one you used.
`--env NAME`	Environment, such as `dev` or `prod`. Default: `dev`.
`--json`	Print machine-readable JSON.
`--quiet`, `-q`	Print only errors.
`--verbose`, `-v`	Print debug output, including HTTP requests.
`--help`	Show help for any command.

The token is read from SYN_TOKEN when set. This is the way to authenticate in CI.

syn login

Opens a browser window to sign in and stores a token in your user configuration. Use --token in environments without a browser.

Flag	Description
`--token TOKEN`	Store an existing token (`syn_live_...`) instead of opening a browser.
`--no-browser`	Print a URL and code instead of opening a browser.
`--sso`	Use single sign-on for your organization.

syn init

Creates synchronoid.yaml and an example pipeline.

terminal

$ syn init my-pipelines --template http_json
Created my-pipelines/synchronoid.yaml
Created my-pipelines/pipelines/example.py

Flag	Description
`--template NAME`	`blank`, `http_json`, `postgresql` or `sftp_csv`.
`--no-git`	Do not create a Git repository.

syn dev

Runs your project on your machine and reloads when files change. Data stays local, in .synchronoid/.

Flag	Description
`--port N`	Port of the local control room. Default 4040 (localhost:4040).
`--asset NAME`	Materialize one asset and exit.
`--partition KEY`	Partition to use together with `--asset`.
`--no-reload`	Disable file watching.

syn deploy

Checks the project, packages it and uploads it. Schedules and sensors start working as soon as the deploy finishes.

Flag	Description
`--env NAME`	Target environment. Required for `prod`.
`--dry-run`	Validate and show changes without uploading.
`--message TEXT`	Note stored with the deploy.
`--yes`	Skip the confirmation prompt.

syn runs

terminal

$ syn runs list --status failed --since 24h
$ syn runs show run_8f3a21 --logs
$ syn runs replay run_8f3a21 --from-layer raw
$ syn runs cancel run_c91d07

Subcommand	Flags
`list`	`--status` (`running`, `succeeded`, `failed`, `retrying`), `--asset`, `--since DURATION`, `--limit N` (default 20).
`show RUN_ID`	`--logs` prints step logs. `--provenance` prints the provenance of produced values.
`replay RUN_ID`	`--from-layer raw\|staged`, `--asset NAME` (repeatable), `--dry-run`, `--verify` (replay against a scratch copy and report differences).
`cancel RUN_ID`	Stops the run after the current step finishes.

syn sources

terminal

$ syn sources list
$ syn sources status company_registry
$ syn sources pause company_registry --reason "provider maintenance"
$ syn sources resume company_registry

pause accepts --reason TEXT and --until TIMESTAMP. resume accepts --no-probe to skip the test request.

syn backfill

Flag	Description
`ASSET`	Asset name (argument).
`--from`, `--to`	First and last partition key, inclusive.
`--partitions LIST`	Comma-separated partition keys.
`--missing`, `--failed`	Select partitions by state.
`--concurrency N`	Partitions in flight. Default 4.
`--downstream`	Also run dependent assets.
`--from-layer raw`	Reuse stored raw data.
`--no-events`	Do not emit change events.
`--dry-run`	Print the plan only.

syn secrets, feeds and alerts

Command	Description
`syn secrets set\|list\|delete\|rollback NAME`	Manage secrets. `set` takes `--stdin`. `rollback` takes `--to VERSION`. See Secrets.
`syn feeds create\|list\|pause\|delete NAME`	Manage subscriptions. `create` takes `--asset`, `--events`, `--webhook` or `--kafka-topic` and prints the signing secret once. See Change feeds.
`syn alerts list\|test NAME`	List rules or send a test message to a channel. See Alerts.

syn materialize, schedules, sensors, connector

terminal

$ syn materialize companies_current --from-layer raw --downstream
$ syn schedules list
$ syn schedules disable nightly
$ syn sensors test new_export_file
$ syn connector test my_connector --fixture sample.json
$ syn --version
syn 0.14.2 (sdk 0.14.2, python 3.12.4)

syn completion bash|zsh|fish prints a completion script for your shell. The CLI also reads SYN_TOKEN and SYN_CA_BUNDLE, and user settings from ~/.config/synchronoid/config.yaml.

syn doctor

Checks the CLI version, token, network access to the API, Python version and project configuration. Use --bundle to create a diagnostics archive for support. See Troubleshooting.

Exit codes

Code	Meaning
`0`	Success.
`1`	Command failed.
`2`	Invalid usage or configuration.
`3`	Not signed in, or permission denied.