CLI reference

The gateline command is the gate frontend in terminal form: it lets a human operator inspect runs, record gate decisions, stage new runs, integrate the framework into a host repository, and serve the Gatehouse web UI. A companion binary, gateline-orchestrator, provides the v1 engine outside a web context. Both are installed by npm install in the framework workspace (packages/, Node 24 or later), run from TypeScript source, and read committed pipeline state directly. The inspect/decide/create groups need no running server. Five binaries ship in all. The other three, gateline-runner-agent, gateline-framework and gateline-fixture, are covered at the end.

gateline — global flags

--repo <path> (repeatable) selects the repository to read runs from. Defaults to the config file (~/.config/gateline/config.yaml), then the current working directory. -V, --version prints the version (0.3.0).

Inspect commands

gateline status

Prints a portfolio table: one row per run showing its phase, gate status (✓/✕/· per PROFILE_GATES), task count (done/total), updated age, and number of items that need a human decision. Also notes how many inbox items await. The phase cell carries a suffix when the run is at rest: (<paused_reason>) for a paused run and (<closure.as>) for a closed one.

No flags.

gateline inbox

Lists everything that needs a human, oldest first. Six kinds of item appear: undecided gates (gate), open escalations (escalation), round-cap pauses (round-cap), other paused runs (paused), staged runs awaiting arm (staged), and bounced packets (malformed). Each is printed with its kind, age, run slug, and title. Bounced packets are prefixed ✕ BOUNCED: <problem>. A gate whose producer is in flight again prints ⋯ SUPERSEDED: <detail> under the item.

gateline show <slug> [artifact]

Prints a run artifact. Without an artifact, lists all artifact paths. With --refs (one of first-line (default), full, off), prints cited R/AC/ADR definitions as footnotes, with their definitions fetched from the run's own spec.md and plan.md. --source <id> disambiguates the slug when the same slug exists in multiple sources.

Decide commands

All decide commands share the same CAS-based write path. They read state.yaml at the run's branch tip, plan a comment-preserving mutation, and commit with a structured message. If a concurrent write moved the ref, the command prints refused (ref-moved): … and exits 2; rerun it. Every other refusal exits 1. A gate decision is accepted only for the gate on the table: the profile's first un-approved gate, while the run stands in one of that gate's phases.

gateline approve <slug> <gate>

Records a named human's gate approval. Required: --burden, one of confirmation | light-correction | heavy-correction (the pilot's headline metric; prompted interactively if the session is a TTY and the flag is omitted). Optional: --notes, --source.

--no-advance records the approval without moving the phase, which is useful when a later gate must also be decided before work resumes.

--hold <reason> implements approve-and-hold: signs the gate and sets phase: paused in the same commit, so a human decision blocking the next phase does not let the engine race ahead. This is the dispatch-safe way to wait. The commit message becomes state(<slug>): G<N> approved by <name> [burden: …] and held (<reason>).

gateline decline <slug> <gate>

Pauses the run as gate-declined. --reason <text> is required. It is the correction channel back to the producing role, so the next iteration has something concrete to address.

gateline resolve-escalation <slug> <index>

Resolves an escalation by its zero-based index: the entry's position in the run's escalations[] list in state.yaml. The inbox lists open escalations but prints no index, so count from the file. --note <text> required. --disposition accepts an optional machine-actionable route: re-review | return-to-implement | re-plan. Omitting it falls back to the engine's default guarded re-review.

gateline pause <slug>

Pauses a run with an optional --reason, one of budget-exhausted | round-cap | escalation | gate-declined (defaults to escalation). The list is the help text's convention, not a validated enum: any string except staged is accepted and written to paused_reason.

gateline resume <slug>

Resumes a paused run. The target phase is derived from the gate ledger (deriveResumePhase walks the profile's gates and finds the first not-yet-approved one) unless overridden via --phase spec|plan|implement|integrate|release. Resuming a gate-declined run re-opens the declined gate. --cost-limit <usd> writes a new budget.cost_limit_usd in the same commit, and is required to resume from a budget-exhausted pause.

gateline close <slug>

Ends a run short of done. Both flags are required: --as is the typed disposition, one of already-delivered | superseded | obsolete | abandoned, and --reason <text> is the comment on it. The commit writes phase: closed and the closure block under the message state(<slug>): closed by <name> [disposition: …]. Nothing is deleted.

gateline reopen <slug>

Undoes a closure. The run returns to the phase its gate ledger derives, under the message state(<slug>): reopened to <phase> by <name> (was closed as <disposition>).

gateline sync

Copies PR-review approvals into state.yaml G2 entries for sources that support it (currently GitHub sources with gh access). Prints the plan by default; pass --live to apply. --source filters to one source. Prints local-only: nothing to sync for sources without a remote. Sync obeys the same gate-on-the-table rule as the decide commands.

Create commands

gateline new

Stages a run: creates the branch and writes intent-brief.md and state.yaml. The run is inert (phase paused, reason staged) and not dispatchable until gateline arm starts it.

The interactive TTY fallback (when slug, title, or brief are missing) uses $VISUAL/$EDITOR (fallback vi) for the intent brief, validates required sections, and demands an explicit stage? [y/N] confirmation. Invalid slugs are rejected before the edit session, so the human's authored brief is never discarded.

gateline arm <slug>

Starts a staged run at the profile's first undecided-gate phase. It refuses a patch run whose work item is still the stub. After the write succeeds, it makes a best-effort call to ensure a draft PR exists (title/description generated from run artifacts, refreshed until a human edits the body).

Serve commands

gateline up

Gatehouse + v1 orchestrator over one clone: the single-authority deployment and the blessed topology. Starts the server (Hono-based, port 4310 default) and the engine in the same process. The engine watches the code tree for fast-forward upgrades and self-supersedes (exit 75) on update. Exactly one --repo is allowed, and it goes before up (it is the CLI's only global option); every flag below is an option of up and follows it.

Key flags:

• --port/--host: bind address (defaults: 4310, 127.0.0.1)
• --adapter (repeatable): headless adapters; first is the default runner
• --spend-limit-usd: defer new dispatches while projected spend across all active runs inside the window exceeds this (a rate limit, never a pause)
• --spend-window: the rolling window the limit measures over, in hours (default 24)
• --no-budget-enforcement: meter but never pause on budgets
• --push / --no-push / --local-only: push mode (--no-push is an alias for --local-only)
• --heartbeat: engine interval (default 180s)
• --role-timeout: wall clock per dispatch (default 1800s)
• --max-concurrent-dispatches: parallelism cap (default 2, 0 disables)
• --no-open: skip launching the browser

gateline ui

Viewer-only web app on localhost, with no engine and no dispatch. Flags: --port, --host, --demo (generated throwaway repo), --no-open.

gateline self-update

git pull --ff-only the code checkout this CLI runs from, then npm install (and npm run build for the web dist) if HEAD moved. Refuses on a dirty tree, and when the install is not a git checkout. A running engine exits 75 at its next tick boundary so it can be restarted on the new code.

Integrate commands

Four commands carry the framework into a host repository and keep it honest there. Each has a dependency-free twin in gateline-framework (below) with the same flags.

gateline-orchestrator

The v1 engine's CLI, installed at gateline-orchestrator. The two binaries take most of the same flags, but in different places: on gateline-orchestrator they are global options, while gateline's only global option is --repo and the rest are options of the up subcommand that must follow up. Common to both: --repo, --adapter (repeatable; later ones satisfy avoid_vendor_of pins), --push/--local-only, --spend-limit-usd, --spend-window, --no-budget-enforcement, --role-timeout, --max-concurrent-dispatches. The orchestrator adds --require-budget (refuse dispatch on any run missing budget.cost_limit_usd) and --gateline-prefix (for hosts that integrated with a custom prefix); gateline up adds the server options --port, --host and --no-open, which the engine does not have. --heartbeat exists on both, as an up option and as an option of gateline-orchestrator watch.

gateline-orchestrator tick

One reconcile pass: sync from origin, derive each active run's next action, dispatch or wait, run the scheduler's sweep tick, and exit. With --dry-run, prints derived actions and moves no refs at all. It is the safe way to verify engine behavior without running live agents.

gateline-orchestrator watch

Resident mode: ref watcher + heartbeat + completions. Runs continuously, waking on branch changes and at the heartbeat interval. --heartbeat overrides the default 180s. It also runs the code-tree monitor, which exits 75 on a clean fast-forward of the checkout.

gateline-orchestrator sweep <role>

Force a scheduled sweep now for the named role, ignoring dueness but not the other schedule guards (enabled, open sweep, same-day, cost cap). Exits 1 when the role has no schedule.

gateline-orchestrator shadow <slug>

Replay a finished run's history against the current engine logic, comparing derived vs. actual actions at each step. Used for the v1 trust ladder's M1 milestone verification. --ref selects a specific rev (default: the run branch, else the default branch).

gateline-runner-agent

A third binary, gateline-runner-agent, implements the workstation half of the remote-dispatch relay: it polls a control plane server's /api/runner/* endpoints for dispatch intents, executes them in a disposable git clone, and reports outcomes back. It has no subcommands.

gateline-framework and gateline-fixture

gateline-framework (packages/framework) is the dependency-free entry point for render, init, validate and fork, long flags only. It runs with nothing installed, which is why a host repository's CI invokes it as node packages/framework/src/main.ts render --check. gateline-fixture (packages/fixtures) generates the demo repository behind gateline ui --demo and the tests; it takes an optional target directory and prints the path it made.