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 server: 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 terminology, progress streams back live, results pull down, and parked units enter the team's review queue. kapi up --local runs the loop on this machine and pushes the results instead.

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 event per line, final = result)
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 the result as the last record	false

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.

The server-side loop, the run entity, and the SSE event stream are specified in AD-022: Convergence as a Service.

Exit Codes

• 0 — Caught up, or parked work reported (target drift is never a failure)
• 1 — Error (network, auth, load)

Related Commands

• kapi push — transport: send source changes to the server
• kapi pull — transport: fetch translations 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 translations 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.