There is a cockpit, too
Everything below drives the control plane one command at a time. When you want to
watch it instead, zipline tui opens a live six-screen cockpit: throughput
and lag, every pipeline, the source-to-sink topology, connected instances, open
incidents, and a running log tail.
zipline │ 1 overview 2 pipelines 3 topology 4 instances 5 incide ● 2.7K r/s p ──────────━━━━━━━━━━──────────────────────────────────────────────────────────── THROUGHPUT │LAG p95 │WAL BACKLOG │UPTIME 1.3K r/s │218ms │408 MiB │1h2m ▇▇▇▇▇▇▇█ -5% │▐░░░░░░░░░░▌ 4% │▐██████▌ recl 3.0G │4 of 7 ok ──────────────────────────────────────────────────────────────────────────────── NEEDS ATTENTION 4 of 7 ›✕ legacy-mssql FAILED failed [p] ▲ inventory-mssql DEGRADED degraded [p] ‖ payments-pg PAUSED paused [r] ● audit-pg RUNNING sink lag Δ40 [p] ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ● 3 more healthy · 1.9K r/s OPEN INCIDENTS 7 · critical critical orders-mssql·to-kafka: route error budget exceeded 1m ago warning payments-pg·to-pg: source paused 20m ago critical inventory-mssql·to-pg: route error budget exceeded 40s ago critical legacy-mssql·to-kafka: source disconnected 25m ago ──────────────────────────────────────────────────────────────────────────────── 1-6 views · tab cycle · q/esc back/quit · ? help · ↑/↓ select · enter detail · p
How it fits together
Zipline has no deploy step. You apply a pipeline spec to the control plane, then bind a live runtime instance to it. Six ideas cover everything the CLI does.
mTLS, not passwords
Every command talks to the control plane over mutual TLS. You present a client certificate - there are no API keys to leak.
Enroll once
Redeem a single-use token; the CA issues you an OU=operator cert, cached locally. Every later command reuses it.
Contexts
A context points the CLI at one runtime (address + cert dir). Switch environments with context use. Stored in ~/.zipline/config.
Pipelines & routes
A pipeline is one source feeding one or more routes (sinks). You describe it as YAML and apply it.
Bindings
A spec is inert until you bind a runtime instance to its source (and sink slots). Bind/unbind is how you wire and unwire delivery.
Profiles & placement
Profiles are reusable connector configs a slot references. Placement decides whether a connector runs in-process or as an external instance.
Common workflows
The everyday operator paths, start to finish.
Onboard a new pipeline
zipline connect rt.internal:9090 --token $ZIP_TOKEN --name prodPoint at a runtime, enroll, and save it as a context - in one step.zipline auth whoamiConfirm your operator identity: common name, OU=operator, and cert expiry.zipline pipeline apply -f orders.yamlRegister the pipeline spec with the control plane.zipline pipeline bind orders --instance src-7f3aBind a live source instance - delivery begins from now.zipline pipeline status ordersWatch it come up: state, bound instance, per-slot placement, incidents.Look around
# everything at a glance - pipelines + instances zipline status # list pipelines, runtimes, and one pipeline in detail zipline pipeline list zipline instance list zipline pipeline status orders # any read command speaks JSON - pipe to jq zipline pipeline list -o json | jq '.[].name'
Lifecycle: pick the right verb
Four ways to stop or steer delivery - they differ in whether resuming leaves a gap.
| Verb | What it does | Data gap? |
|---|---|---|
| pause / resume | HOLD a route (--route) or the source, then continue. Resume picks up from the held cursor. | No - exactly where it left off |
| disable / enable | Detach a sink route and release its WAL floor; keep the binding. Enable re-attaches. | Yes - re-attaches from now |
| unbind | Clear the binding entirely (whole pipeline, or one sink slot with --route). Re-bindable. | Yes - resumes from now on re-bind |
| skip | Accept the loss of a corrupt frame on a stalled route so the cursor can advance past it. | One frame, deliberately |
Recover a stalled pipeline
# clear every stalled route at once zipline pipeline skip orders --all # swap to a healthy source instance without an explicit unbind zipline pipeline bind orders --instance src-new --force
Everyday commands
The commands you reach for daily. The full reference covers connectors, tokens, route editing, and every flag.
Point at a runtime and authenticate - the onboarding command. Saves a context and, if you pass a token, enrolls into it in one shot.
| Flag | Type | Description |
|---|---|---|
| --token | string | Operator enroll token (or use --token-file). |
| --name | string | Context name to save. Defaults to default. |
| --enroll | string | Enroll-plane address. Defaults to the control port + 2. |
zipline connect rt.internal:9090 --token $ZIP_TOKEN --name prod
Redeem an operator enroll token for an operator client cert. Cache-first and idempotent - a valid cached cert is reused.
| Flag | Type | Description |
|---|---|---|
| --token | string | Operator enroll token. |
| --token-file | string | File containing the operator enroll token. |
| --enroll | string | Enroll-plane address (env ZIPLINE_ENROLL). Defaults to the control port + 2. |
zipline auth enroll --token-file ./operator.tok
Show the current operator certificate identity - common name, OU, and expiry - read straight from the local cert cache. No control-plane round-trip.
zipline auth whoami
common_name: operator-ada
ou: operator
expires: 2026-09-28T12:00:00ZSwitch the current context - the runtime address, cert dir, and output format every command inherits. Pair with context current to see what's active.
zipline context use staging
zipline context currentApply a pipeline spec - YAML via -f or stdin. Creates or updates the pipeline on the control plane.
zipline pipeline apply -f orders.yaml # or from stdin cat orders.yaml | zipline pipeline apply -f -
Dry-run a spec and print the diff - route changes, whether the source restarts, commit-mode changes - without applying anything.
zipline pipeline plan -f orders.yaml
List pipelines with name, state, and bound instance.
zipline pipeline list
NAME STATE INSTANCE
orders running src-7f3a
audit pending (unbound)Print a pipeline's status: state, bound instance, incidents, and a per-slot table (role, route, state, placement, profile).
zipline pipeline status ordersPrint a pipeline spec as canonical YAML - handy for review, version control, or feeding back into apply.
zipline pipeline get orders > orders.yamlBind an instance id to a pipeline (source) or a sink slot (with --route). This is what actually starts delivery.
| Flag | Type | Description |
|---|---|---|
| --instance * | string | Runtime-minted instance id to bind. |
| --route | string | Sink-slot route name. Omit to bind the source. |
| --force | bool | Unbind any conflicting binding first, then bind. |
zipline pipeline bind orders --instance src-7f3a # bind an external sink to a named route zipline pipeline bind orders --route warehouse --instance sink-22b1
Clear the binding for a pipeline, or a single sink slot with --route (the route stays in the spec and is re-bindable).
zipline pipeline unbind orders --route warehouse
Delete a pipeline from the control plane.
zipline pipeline delete auditPause a sink route (--route) or the source (no --route). Pause is a HOLD - resume continues from the held cursor with no gap.
# hold the source, then continue later - no data gap zipline pipeline pause orders zipline pipeline resume orders
Disable a sink route - detach + release the WAL floor, keeping the binding. Enable re-attaches from now (any events during the gap are skipped).
zipline pipeline disable orders --route warehouse zipline pipeline enable orders --route warehouse
Accept the loss of a corrupt frame on a stalled route so its cursor can advance. Pass a route, or --all to clear every stalled route.
zipline pipeline skip orders warehouse zipline pipeline skip orders --all
Create or update a reusable connector profile from a YAML file. Pipelines reference profiles instead of repeating connector config.
zipline profile apply -f pg-prod.yaml zipline profile list
Store a secret value under a ref. The value is a positional arg (kept out of flag history) and is never echoed back - list shows refs only.
zipline secret set pg-prod/password 's3cr3t' zipline secret list # names only, never values
Aggregate pipeline + instance overview in a single dial - counts, a pipelines table, and an instances table.
zipline status
3 pipelines, 4 instances, 2 boundList runtime instances: instance id, display name, role (source / sink), and the pipeline they're bound to.
zipline instance list
Print the zipline version.
zipline version
zipline v2.4.1Tips & tricks
JSON for scripting
Every read command speaks structured output. Add -o json and pipe to jq - or -o yaml for a human diff.
A context per environment
Keep prod, staging, and dev contexts. context use prod once, then drop the --runtime flag from every command.
The operator cockpit
Run zipline tui, or just zipline on an interactive terminal, for a live six-screen view of the runtime. See what it looks like.
Quiet in CI
Pass -q to suppress confirmation chatter on mutations. The exit code still tells your pipeline whether it worked.
Plan before you apply
pipeline plan -f spec.yaml shows the diff - including whether the source must restart - before apply touches anything.
Secrets are write-only
secret set takes the value as a positional arg and never prints it back. secret list returns refs, never values.
Global flags
These apply to every command. Precedence is flag > environment variable > context profile > default. The full reference lists them all.
| Flag | Env var | Description | Default |
|---|---|---|---|
| --context | ZIPLINE_CONTEXT | Context profile to use | current |
| --runtime | ZIPLINE_RUNTIME | Control-plane address (mTLS); overrides the context | - |
| --cert-dir | ZIPLINE_CERT_DIR | Operator cert cache dir; overrides the context | - |
| -o, --output | ZIPLINE_OUTPUT | Output format: text, json, yaml | text |
| --timeout | - | Per-RPC timeout | 10s |
| -v, --verbose | ZIPLINE_VERBOSE | Debug logging | false |
| -q, --quiet | ZIPLINE_QUIET | Suppress non-error output | false |
Install the CLI
A single static binary. Pick your platform.
brew install zipline-run/tap/zipline # or, no Homebrew - one-line installer curl -fsSL https://zipline.run/install.sh | sh # verify zipline version
Upgrade with brew upgrade zipline, or re-run the installer to pull the latest release.
# Scoop scoop install zipline # winget winget install Zipline.CLI # or PowerShell one-liner irm https://zipline.run/install.ps1 | iex
All three land zipline.exe on your PATH. Verify with zipline version.
Direct downloads
Prefer a raw binary? Grab one for your platform.
Every binary self-reports its build: run zipline version after install.