kapi up

$ kapi up

Bring the project up to date: the recipe declares the languages, the flow, and the gates that decide shippable; kapi up runs the project's default flow (defaults.flow) over every target language, looping until every gated scope is shippable or parked for a human.

Without defaults.flow, up runs the built-in default flow — Memory reuse (recycle) followed by AI translate — so a recipe needs no flow YAML at all to catch up. Setting defaults.flow replaces the built-in default.

Before each pass, up re-syncs the project block store with the working tree: edited source files, a store written by another kapi version, or a missing store trigger a re-extraction (the same shared path behind the desktop's Re-extract). --no-extract opts out.

Each pass re-derives coverage from the working tree, runs the flow only for the locales still short of their gate, and stops when everything ships, a pass makes no progress (the remainder parks — it needs a human), or the pass cap is reached. After each pass the project's bound checks run over what was produced: a unit with failing findings (dropped placeholders, terminology violations) counts as drafted, not translated, so it cannot lift its locale over the gate until fixed. --no-checks opts out.

When the loop ends, the materialize policy decides whether target-language files are written from the project store: 'defaults.materialize: on-converge' (or the --materialize flag) writes them for every locale whose gated scopes are all shippable; the default ('manual') leaves that to 'kapi merge'.

Venue: in a server-connected project (a recipe with a server: block, with the bowrain plugin installed) the loop runs on the Bowrain server by default — on the org's keys, against the org's shared Memory and terminology — and this command pushes local changes, streams the server run's live progress, and pulls the produced targets. --local keeps the loop on this machine and then pushes the results so the server never goes stale; --server fails rather than falling back to a local run. The resolved venue is printed first whenever a server: block is present. Without a server: block, up is purely local.

--plan is a dry run in every venue: instead of running anything, up reports the pending work per (collection, locale) — units missing a target, exact Memory leverage, the remaining AI work, and a rough token estimate — computed locally against the working tree, with no provider calls and no writes. Combine with --json for agents.

up never fails the build on target drift: parked, pending target content is normal toil, reported rather than thrown. Use 'kapi status' to inspect standing without running anything, and 'kapi check --ship' to enforce the gates (e.g. before a release tag).

--passes 1 runs a single pass (the behavior of the bare 'kapi run'); --passes N caps the loop at N passes.

Commandup

Groupwork

Try it

Runs in your browser against a small sample file. Edit the command before running, or press Run to execute it as shown.

$ kapi up # loop the default flow until every gated scope ships or parks

Flags

Flag	Type	Default	Description
--api-key	string		API key for the AI provider
--batching	string		how many blocks share one LLM call: auto (default), single
--concurrency, -j	int	0	number of files to process at once (0 = auto)
--context	string		what the model is told about a block besides the block: none, key (default), neighbours
--credential	string		saved credential name to use (see 'kapi credentials list')
--encoding, -e	string	UTF-8	input file encoding
--explain	bool	false	print the resolved source → sink bindings and exit without running
--format, -f	string		override input format detection
--input, -i	stringSlice		input file path(s); repeat for multiple files
--instruction	string		extra guidance for the model while translating (e.g. "informal register; keep product names in English")
--jobs	int	0	how many languages to catch up concurrently per pass (0 = the recipe's defaults.jobs, else 4)
--json	bool	false	output the structured result as JSON
--local	bool	false	run the loop on this machine even when the recipe declares a server (the results are then pushed so the server stays current)
--materialize	bool	false	after the loop, write target-language files from the project store for every shippable locale (forces defaults.materialize: on-converge)
--memory	string		named Memory for recycle flow (resolves from KAPI_HOME)
--model	string		AI model name
--no-checks	bool	false	skip the bound checks in the loop (produced units count as translated even when failing guardrails)
--no-extract	bool	false	skip the pre-pass source-drift check and block-store re-extraction
--output, -o	string		output path or template (e.g. ./out/{name}_{lang}.{ext})
--pack	bool	false	when transforming a .kpz, also eject the result to the .kpz (auto-pack)
--parallel-blocks	int	0	fan out block processing across N goroutines (0 = off)
--passes	int	0	maximum reconciliation passes (0 = loop until up to date or parked, capped at 5; 1 = single pass)
--plan	bool	false	dry run: report pending work, content-memory leverage, and a token estimate per (collection, locale) — no provider calls, no writes
--project, -p	string		path to a kapi.yaml project recipe or its directory (auto-discovered from cwd if omitted)
--provider	string	anthropic	AI provider (anthropic, openai, ollama)
--server	bool	false	require the server venue: fail rather than run the loop locally when the recipe has no server or the server plumbing is unavailable
--source-lang	string	en	source language (e.g. en, en-US)
--stats	bool	false	include part/block counts in output
--target-lang	string		target language (e.g. fr, de-DE)
--termstore	string		named terms store for term-lookup/enforce (resolves from KAPI_HOME)
--timeout	duration	15m0s	server venue: maximum time to wait for the server run to finish before pulling available results
--trace	string		write flow trace JSON to file (for flow visualization)

More examples

$ kapi up --plan # dry run: pending work, content-memory leverage, and a token estimate per locale

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

$ kapi up --materialize # also write target-language files for the shippable locales

$ kapi up --local # connected project: run the loop on this machine, then push the results

$ kapi up -p kapi.yaml # bring an explicit project recipe up to date

← Back to the Command Reference