CLI Reference#

Complete command-line interface documentation.

interlace [OPTIONS] COMMAND [ARGS]

Shared Options#

Most commands accept a common set:

interlace init#

Scaffold a new interlace project from a template.

interlace init [PATH] [--name/-n NAME] [--template/-t NAME] [--list]

Copies a template into the directory: interlace.yaml, its models, and a README. --template/-t chooses the starter (default quickstart, a no-source SQL → Python → SQL chain); --list prints the available templates and any credentials each needs. --name defaults to the directory name. Fails if the directory is already initialised.

interlace plan#

Show what apply would change in an environment. Runs no SQL.

interlace plan [--env] [--path] [--select] [--forward-only] [--json]

Output classifies each change (added, modified, removed) with a category (breaking, non_breaking, forward_only) and whether the model will rebuild or reuse, plus any cross-engine transfers.

interlace apply#

Build changed models and promote the environment.

interlace apply [--env] [--path] [--select] [--forward-only] [--force] [--parallelism]

Exits 1 on a breaking plan without --force, or when a blocking check fails.

interlace run#

Force-build models and promote, ignoring change detection. For incremental_by_time models, --start/--end set the catchup window (default: the latest grain interval); intervals already in the ledger are skipped.

interlace run [--env] [--path] [--select] [--start ISO] [--end ISO] [--parallelism]

interlace restate#

Reprocess incremental models over a window, ignoring the interval ledger (vs run, which skips filled intervals).

interlace restate [--env] [--path] [--select] [--start ISO] [--end ISO] [--parallelism]

--start/--end must be ISO timestamps (exit code 2 otherwise); timezone-aware values are converted to local time.

interlace models#

List models with their materialisation, strategy, engine, and dependencies.

interlace models [--path] [--select] [--json]

interlace lineage#

Show a model’s lineage — table-level, or column-level with --columns.

interlace lineage MODEL [--path] [--columns/-c] [--format/-f text|json|dot]

dot output is Graphviz — pipe to dot -Tsvg.

interlace impact#

Column-level blast radius: every downstream column transitively derived from MODEL.COLUMN, plus opaque consumers (Python models and * projections that read the source model whole). Compile only.

interlace impact MODEL.COLUMN [--path] [--json]

Same data as the HTTP GET /models/{name}/impact.

interlace query#

Run a read-only SELECT against the warehouse and print the result. SELECT only — the same parse-time fence as the web console (real tables and views, never table functions or file readers). Unqualified names resolve to the promoted (prod) views; capped at --limit rows (max 10,000).

interlace query "SELECT * FROM raw_events" [--path] [--limit/-n 100]

The CLI counterpart of the POST /query console.

interlace runs#

Recent runs from the durable queue (newest first). The trigger column derives from each run’s idempotency key: cron, interval, api, or stream.

interlace runs [--path] [--limit/-n 20] [--json]

interlace cancel#

Cancel a run: queued cancels now; running cancels at the worker’s next heartbeat.

interlace cancel RUN_ID [--path]

interlace streams#

Declared streams with their log head and warehouse watermark.

interlace streams [--path] [--json]

interlace engines#

Configured execution engines (models pin to these with engine:). Credentials in DSNs are redacted.

interlace engines [--path] [--json]

interlace gc#

Garbage-collect snapshots no environment references, and their physical tables.

interlace gc [--path] [--grace 7d] [--dry-run]

Also trims old events, check results, and finished queue rows, and sweeps stream retention.

interlace scheduler#

Run the scheduler loop only (no HTTP): tick triggers, flush streams, drain due runs, and sweep stream retention. Needs a live warehouse.

interlace scheduler [--env] [--path] [--interval 60.0] [--once]

--once runs a single tick + drain, then exits.

interlace serve#

Run the interlace daemon: HTTP API + scheduler in one process. Requires the service extra.

interlace serve [--env] [--path] [OPTIONS]

interlace env#

Inspect and manage environments.

interlace env list [--path] [--json]                       # promoted models + drift per environment
interlace env drop NAME [--path] [--force]                 # drop views; snapshots become gc-reclaimable
interlace env rollback [NAME] [--to N] [--list] [--json]   # repoint views at an earlier promotion

Dropping prod requires --force.

env rollback repoints an environment’s views at an earlier promotion generation — nothing rebuilds. --to N selects a generation (default: the one before the latest); --list shows the promotion history instead (state only). The rollback itself needs a live warehouse.

interlace checks#

Run and inspect data-quality checks.

interlace checks run [--env] [--path] [--select] [--json]
interlace checks list [--path] [--model/-m NAME] [--limit/-n 20] [--json]

checks run verifies an environment’s promoted tables without rebuilding; results are recorded; exits 1 when any error-severity check fails.

interlace apikey#

Manage HTTP API keys.

interlace apikey create NAME [--scope read] [--scope write] [--scope admin] [--path]
interlace apikey revoke NAME [--path]
interlace apikey list [--path]

create prints the ilk_ token once. revoke disables every key with that name immediately (it refuses to remove the last remaining key — that would disable auth).

Selectors#

--select/-s is repeatable, and each value may list several selectors separated by commas or spaces; the results are unioned. Accepted by plan, apply, run, restate, models, and checks run.

Affixes compose with tag: and state: (tag:x+, state:modified+). An empty state:modified match is legitimate — it just means nothing changed.

Exit Codes#