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, because 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) still counts as translated, which it is, and holds its locale out of shipping until the finding is fixed. 'kapi status' runs the same checks and reports the same verdict. --no-checks opts out.

The materialize policy decides whether the run owns delivery of the target-language files. Under 'defaults.materialize: on-converge' (or the --materialize flag) it does, and the ship gate holds it back: each pass drafts into a run-local tree, and only a locale whose gated scopes are all shippable has its files written where the recipe points, and a parked locale's files are absent, not merely unblessed. The default ('manual') leaves delivery to 'kapi merge' and claims no gate.

Venue: in a server-connected project (a recipe with a bowrain: 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 the recipe connects to a server. Without that 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		input file encoding
--explain	bool	false	print the resolved source → sink bindings and exit without running
--fail-on-incomplete-watch	bool	false	server venue: fail when the run's event stream ends before the run does, instead of reporting it and pulling what landed
--fail-on-unknown	bool	false	exit with error if any file cannot be processed (default: skip with a warning)
--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), with no provider calls and 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		source language (e.g. en, en-US; defaults to the project's source_language, else en)
--stats	bool	false	include part/block counts in output
--strict	bool	false	alias for --fail-on-unknown
--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