CLI Reference

Full reference for all nanosync CLI commands — start, create, list, run, monitor, schema, and more.

Nanosync uses a verb-first command structure: nanosync <verb> <noun> [args] [flags].

Global flags

Flag	Default	Description
-c, --config	nanosync.yaml	Path to the config file
--context	active context	Nanosync context to connect to
--log-format	auto	json or text (auto-detected: text on TTY, JSON otherwise)

---

Daemon verbs

start dev

Start in development mode. Uses an embedded SQLite database. Config is optional — when omitted, the server loads everything from the embedded store.

nanosync start dev [--config <path>] [--api-addr <addr>] [--db-data-dir <dir>]

Writes the dev context to ~/.nanosync/config so subsequent client commands connect automatically.

start server

Start in production mode. Config is required. Designed to run under a process supervisor (systemd, Docker, Kubernetes).

nanosync start server --config <path> [--api-addr <addr>] [--db-data-dir <dir>]

Flag	Default	Description
--config	—	Path to nanosync.yaml (required)
--api-addr	:7600	Address for the HTTP API server
--db-type	sqlite	Database backend: sqlite or postgres
--db-dsn	{data-dir}/nanosync.db	SQLite file path or Postgres connection string
--db-data-dir	~/.nanosync/data	Directory for the SQLite state file

---

CRUD verbs

list

nanosync list pipelines             [-o table|json]
nanosync list connections           [-o table|json]
nanosync list connectors            [-o table|json]
nanosync list tables <conn-name>    [--schema <name>] [-o table|json]

list tables connects to the named connection and returns available tables with row counts.

get

nanosync get pipeline <name>        [-o table|json]
nanosync get connection <name>      [-o table|json]

create

# Create a pipeline from a file
nanosync create pipeline --file <path> [--dry-run]

# Create a pipeline inline
nanosync create pipeline \
  --name my-pipeline \
  --source-connection prod-postgres \
  --sink-connection prod-bigquery \
  --tables public.orders

# Create a connection (interactive wizard)
nanosync create connection --name prod-postgres --type postgres

update

nanosync update pipeline   <name> --file <path>
nanosync update connection <name> [--type <t>] [--dsn <dsn>] [--property key=val]

delete

nanosync delete pipeline   <name>
nanosync delete connection <name> [--force]

--force skips the confirmation prompt and also stops the pipeline if it is running.

---

Lifecycle verbs

run

Tell the server to start a pipeline (non-blocking).

nanosync run pipeline <name>

stop

nanosync stop pipeline <name>    # stop one pipeline
nanosync stop                    # stop the daemon

status

nanosync status                  # server health + worker fleet
nanosync status pipeline         # state of all pipelines
nanosync status pipeline <name>  # state, lag, last checkpoint for one pipeline

---

Inspection / monitoring verbs

logs

nanosync logs pipeline <name> [--limit N] [--follow] [-o table|json]

metrics

nanosync metrics pipeline <name> [-o table|json]

Returns throughput (events/s), replication lag, and last checkpoint timestamp.

monitor

Live full-screen TUI dashboard showing throughput, lag, snapshot progress, and worker fleet.

nanosync monitor pipeline <name>

Keys: ↑↓ navigate, Enter drill down, w worker fleet, q quit.

test

Test connectivity for a connection or validate a pipeline config.

nanosync test connection [<name>]                              # test a named connection
nanosync test connection --type postgres --dsn "postgres://..."  # ad-hoc test
nanosync test pipeline <name>                                  # validate config + dry-run connect

---

Config verbs

apply

Reconcile a YAML config into the running server. Idempotent — upserts all connections and pipelines, leaves unchanged resources untouched.

nanosync apply [--file <path>] [--dry-run]

stream

Run a pipeline in the foreground without starting the HTTP API server. Useful for one-off migrations or debugging. Streams directly to stdout if no sink is configured.

nanosync stream \
  --source "postgres://user:pass@localhost:5432/mydb" \
  --tables "public.orders"

---

Schema verbs

Used when a pipeline is paused in pending_schema_approval state (see schema_mapping.conflict: approve).

schema review

nanosync schema review <pipeline>

schema approve

nanosync schema approve <pipeline>

---

Output formats

Most commands accept -o table (default) or -o json.

nanosync list pipelines -o json | jq '.[].name'

---

Common workflows

# Start dev server
nanosync start dev --config nanosync.yaml

# CRUD
nanosync list pipelines
nanosync get pipeline orders-to-bigquery
nanosync create pipeline --file pipeline.yaml
nanosync create connection --name prod-postgres --type postgres
nanosync delete pipeline orders-to-bigquery
nanosync delete connection prod-postgres --force

# Lifecycle
nanosync run pipeline orders-to-bigquery
nanosync stop pipeline orders-to-bigquery
nanosync status pipeline

# Inspect
nanosync logs pipeline orders-to-bigquery --limit 50
nanosync metrics pipeline orders-to-bigquery
nanosync monitor pipeline orders-to-bigquery

# Apply a config file
nanosync apply --file nanosync.yaml
nanosync apply --file nanosync.yaml --dry-run

# Config reload without restart
kill -HUP $(pgrep nanosync)