kapi up

Catch the project up to its ship gates: the verb that runs the kapi loop. kapi up treats the recipe as the desired state and runs the project's default flow over all content across every target language, looping until every gated scope is shippable or parks for a human.

On a server-connected project (the recipe declares a bowrain: block), kapi up runs the loop on the Bowrain server by default: it pushes drift, the server runs the loop on the organization's keys and shared content memory and terms, progress streams back live, results pull down, and parked units enter the team's review session. kapi up --local runs the loop on this machine and pushes the results instead.

The push phase reports the verdicts the server did not accept, per language, in the lines kapi push prints. With --json they arrive as one governance record in the stream.

kapi push and kapi pull remain as pure transport: they move project state and never translate. There is no kapi sync; a connected kapi up is push → catch up → pull.

Usage

kapi up [flags]

Examples

# Catch the project up on the server (connected project), streaming progress
kapi up

# Dry run: pending work, memory reuse, and a token estimate per locale; no writes
kapi up --plan

# Catch up on this machine (your AI keys), then push the results
kapi up --local

# NDJSON event stream for CI and agents (one record per line, including a result record)
kapi up --json

# A single pass over every locale that needs work
kapi up --passes 1

Options

Flag	Description	Default
--plan	Dry run: report pending work, memory reuse, and a token estimate; no writes	false
--local	Catch up on this machine, then push the results (override the server venue)	false
--server	Require the server venue: fail rather than fall back to a local run	false
--timeout	Server venue: maximum time to wait for the server run before pulling available results	15m
--passes	Maximum reconciliation passes (0 = loop until caught up or parked; 1 = one)	0
--jobs	How many languages to catch up concurrently per pass	4
--materialize	After the loop, write target files for every shippable locale	false
--no-extract	Skip the pre-pass source-drift check and block-store re-extraction	false
--no-checks	Skip the bound checks in the loop	false
--json	Stream the convergence events as NDJSON, with one result record	false
--fail-on-incomplete-watch	Server venue: fail when the event stream ends before the run does, instead of reporting it and pulling what landed	false

With --json, read the outcome from the record whose type is result. On the server venue, and in a project with no server, it is the last record. After kapi up --local on a connected project, the push that follows the local run writes its records after it: a changeset record when it proposed terminology edits, a voice_profile record when the recipe binds a voice profile, and a governance record when the server did not accept a verdict.

On the server venue the stream opens with a run_started record carrying the run's id, and the result record carries run (id, state, passes, as kapi status --json reports them) beside watch, which says whether this client saw the whole run and what ended it (done, timeout or stream_error). A consumer that loses the stream still holds the run's id, and kapi status reports where that run got to.

The loop

Each pass re-derives coverage from the working tree, runs the flow only for the locales still short of their gate, then runs the project's bound checks over what was produced. The loop stops when every gated scope is shippable, a pass makes no progress, or the pass cap is reached. Whatever cannot be advanced unaided parks: reported as awaiting a human, exit 0. kapi up never fails the build on target drift.

Locales are caught up concurrently within a pass (--jobs, default 4). Before each pass, up re-syncs the block store with the working tree (--no-extract opts out).

Two venues, one event stream

On a connected project the run executes on the server and streams the same convergence events the CLI renders locally, so the terminal view is identical either way.

Exit Codes

The exit code answers whether the work happened, not whether this command watched it happen. A server run outlives the connection that watches it: when the stream ends early, up says so, pulls what landed, and reports the run's state as the server holds it.

• 0: caught up, parked work reported (target drift is never a failure), or the run went on after the event stream ended early
• 1: the work did not happen or its outcome is unknown: a failed or canceled run, a push or pull that failed, a run that never started, a truncated --json document, or an interrupted command
• --fail-on-incomplete-watch moves a watch that ended early into 1, for a pipeline that would rather stop than proceed on a partial view

Related Commands

• kapi push: transport: send source changes to the server
• kapi pull: transport: fetch results from the server
• kapi status: standing: coverage, gates, and what's pending

When to Use

Use kapi up for the daily reconcile, bringing every locale up to date against the project's gates, locally or on the server:

• CI/CD pipelines: kapi up --json from a workflow to catch up on push and fail only on an explicit kapi check --ship gate; see The loop in CI for the ready-made surfaces.
• Developer workflows: update source content, then kapi up to get results back and see what still needs a human.

For a custom one-off pipeline (one named flow, one pass, no gate loop), use kapi run <flow> instead.