kapi pull

Bring the team's work into your checkout: the results of server runs and review, the workspace's governed terms, and the recipe changes a person approved. kapi pull only moves content and drafts nothing. A teammate in the browser or in Kapi Desktop sees the same results on the server.

Usage

kapi pull [flags]

Examples

# Pull everything that changed on the server
kapi pull

# Pull only French results
kapi pull --locale fr

# Pull several locales
kapi pull --locale fr --locale de

# Show what would be pulled without changing files
kapi pull --dry-run

# Re-download everything, unchanged blocks included
kapi pull --force

# Refresh only the workspace's governed terms into the local terms store
kapi pull --concepts

# Example output:
# Pulled 12 blocks for 2 locales
# Updated 4 file(s)

Options

Flag	Description	Default
--locale	Target locales to pull (repeatable)	all
--force	Re-download everything, ignoring what the tree already holds	false
--dry-run	Show what would be pulled without changing files	false
--concepts	Sync only the workspace terms (concepts + relations) into the local terms store; no content transport, no automations	false

What pull writes

A pull reads the server's tree and the changes since the ref the client last committed or pulled (the protocol is described once, on kapi push), and writes several things into the tree:

• Recipe changes, first. When a person approved an axis a context scan proposed, the approval is waiting as a pending recipe change. Pull writes it into kapi.yaml as defaults.coordinates.<axis> and marks it settled on the server. A value the recipe already holds counts as applied. A value that disagrees with the recipe is reported as a conflict for you to resolve. You review recipe changes in git, so a failure here never fails the pull.
• Content. Targets produced by runs and promoted by review land in the target files the recipe's collections: name, with the format's own writer. A file whose targets did not change is left untouched.
• Decisions. Review decisions made on the server are recorded in the project's decision ledger, where they take effect at once and every checkout of the project reads them. The pull writes no file.
• Governed terms. When the project is claimed into a workspace, pull snapshots the workspace's concepts and their relations into the project's terms store and records a baseline, so a later kapi push can diff local terms edits against it and kapi check --ship gates offline against the same governed terms.

Pull also reports what it did not apply:

• Retired items. Pull skips an item the server still sends when its source is gone from this checkout.
• Blocks without a file. A block the server sends with an empty item name, or with one that points outside the project, has no file to land in. Pull skips it, prints how many it skipped with the first block ids, and moves past it, so the next pull continues from there.
• Governance divergence. Pull reports the collections the server holds and how it governs them. For a collection this recipe declares, kapi.yaml decides. Pull reports a point, channel or voice that differs on the server, and you resolve it in git.

Exit codes

• 0: success (changes pulled or already up to date)
• 1: error (server unavailable, auth failed, and so on)

Related commands

• kapi push: the protocol, and what a push declares
• kapi status: coverage, ship standing, and what is pending
• kapi diff: the changed blocks, per file
• kapi up: push, run on the server, pull

When to use

Pull from Bowrain Server to:

• Fetch results of runs and review completed by teammates
• Take an approved axis into the recipe, for review in git
• Sync governed terms, so kapi check --ship gates offline
• Update source content that entered Bowrain through another connector

Source content can also come from a server-side connector: a content platform, a design tool or a git host. kapi pull brings those changes down, so the checkout mirrors content that entered Bowrain elsewhere.