kapi up

Catch every language up to the project's ship gates. On a connected project the work runs on the Bowrain server, with the organization's keys and the shared content memory and terms, and what needs a person goes to the team's review session. The Run now button in the project's Runs view starts the same run from the browser or the desktop app.

kapi up runs the kapi loop. It treats the recipe as the desired state and runs the project's default flow over all content in every target language, looping until every gated locale is shippable or waits for review.

On a server-connected project (the recipe declares a bowrain: block), kapi up runs the loop on the Bowrain server by default:

1. It pushes what drifted.
2. The server runs the loop, and progress streams back live.
3. The results pull down, and translations waiting for review 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 only move project state and never translate. There is no kapi sync: a connected kapi up pushes, catches up, then pulls.

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 up to date or waiting for review, capped at 5; 1 = single pass)	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 locale is shippable, a pass makes no progress, or the pass cap is reached. Anything a flow cannot advance without a person waits for review: kapi up reports it as awaiting a person and exits 0. Target languages that are behind never fail the build.

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 events the CLI renders locally, so the terminal view looks the same on either venue.

Exit Codes

The exit code reports whether the work happened. A server run continues if the connection watching it drops. 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, work waiting for review 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 every day to bring 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.