← Docs · The ki CLI

Every ki command

All 121 commands, in the 18 groups the CLI itself divides them into. The groups are ordered by scope: what affects your machine, then what affects one repository, then what affects the estate.

This inventory is vendored, not rewritten. ki ships a manual page, and this page takes it verbatim from v0.13.0 - every invocation and every description below is the tool's own text, parsed rather than paraphrased. A command renamed, added, or withdrawn upstream cannot leave this site describing one that is not there.

What the site adds is the routing around it. If you do not know which command you want, the CLI overview explains what each group is for and which concept page covers it. If you know the outcome but not the mechanism, choose a skill by outcome may be the better starting point, because much of what ki does is activate a capability rather than perform the work itself.

Reading an entry

An invocation is written the way the manual writes it. <angle-brackets> mark a value you supply, [square brackets] mark an optional part, | separates alternatives, and ... marks a repeatable option. [repo-options] stands for the repository selectors in the Repository options group, which any ki repo command accepts.

The version you have installed is the authority on exact grammar. ki --help and ki <command> --help answer from your binary; this page answers from v0.13.0, which is the release this section describes.

General

Use these commands to invoke KI; use --help for command-specific guidance.

ki [command]

Run a KI command, or print root help when no command is supplied.

ki help [command...]

Print general help or help for a command path, including nested commands.

Global options

Use these options with ki or any KI command to print command help or the CLI version.

--help, -h

Print help for KI or the selected command.

--version, -V

Print the CLI version.

Installation

Use this command to bootstrap the user-managed KI environment.

ki bootstrap

Create the user-managed KI environment configuration from detected supported agents, install the built-in verified canonical harness, then install the core user skills — ki-bootstrap, ki-next, ki-plan, and ki-recap — into every configured agent's user skill directory. An existing agent configuration is reused without replacement. Pass --refresh to redetect every supported runtime and rebuild the user configuration's agents, installed harnesses, and KI-managed user skill links. When the canonical harness is in local development, bootstrap keeps that binding and installs the core user skills from the local checkout. If the binding cannot be kept, it prints a warning naming the reason before restoring the verified archive and re-pointing the configured canonical skills to it. During a refresh only, KI imports the retired [repositories].paths list into keyed records in $XDG_STATE_HOME/ki/registry.toml and removes that list from user configuration. Normal repository, trade, and Territory resolution never reads the retired path list.

Local management

Use these commands to inspect the local KI installation, user configuration, and repository state without changing it.

ki harness search <query>

Search only verified installed local harness capabilities. The required non-empty query matches case-insensitively against a harness identifier, capability kind, or capability name. Results are sorted by harness identifier, capability kind, and capability name. The command neither discovers a repository nor consults a registry or the network. When no capability matches, it succeeds and reports that no matching installed capabilities exist.

ki completion <shell>

Print Bash or Zsh completion source to standard output. The generated scripts follow the complete registered command tree, offer valid option names at every reachable command, complete documented closed values, and delegate repository selection, capture-directory, and output-directory values to the shell's native path completion. They do not invoke KI, consult the network, or invent dynamic identifiers.

ki harness outdated

Report installed harnesses only when comparable newer release evidence is available; it names unavailable evidence rather than claiming freshness.

ki harness missing

Report desired user capabilities that have no installed provider.

ki update [--cli]

Refresh installed configured harnesses. The executable updates only when a verified installer receipt proves that it owns the running regular executable. Use --cli to require that executable target. Linked development and externally managed executables, including Homebrew installations, are not self-updated.

ki cleanup

Report only stale artefacts in a persisted, versioned KI-owned format. V1 has no such format, so this command reports that no eligible managed stale state exists and changes no files. It does not infer that cache contents, transaction-looking directories, unconfigured harnesses, links, or unknown files are stale.

ki diag [--full]

Print share-safe tool/version, proven local/release/unknown installation mode, executing host platform and architecture, runtime/version, configuration and registry status, and counts without changing state. With --full, include local paths, identities, and detailed configuration diagnostics. It does not inspect repository declarations or projections. Local provenance requires a resolved development checkout matching this tool's source/package layout and a Git checkout or worktree marker. Copied source without that evidence reports unknown; a source URL alone is insufficient.

ki doctor

Check the user configuration, configured agent skill directories, installed harnesses, and configured KI user-skill links without changing state. It also reports direct-CWD legacy .ki-meta/ and .ki/ directories, without searching for or operating on a repository. It validates a regular direct-CWD .ki.toml declaration without resolving its providers. For every registered Knowledge Base it warns once per declared external store that is unavailable on this host, naming its fix, and passes when every declared store is available or marked absent; a warning never changes the exit status. A failing check produces a non-zero exit status after the complete report. Report the same context as diag, the read-only scope, verdict, and pass/warn/fail/skipped counts. Health does not imply package or release freshness.

ki repair [--apply | --dry-run]

Preview repairs by default; --apply explicitly authorises changes. Reconcile configured user-skill links from their installed or active local harness sources. It creates missing links and re-points stale or dangling symbolic links. It also removes a recognised legacy schema = 1 line from valid user configuration; newly written configuration is unversioned. It never installs a harness, removes legacy repository state, or repairs repository projections. It reports unavailable sources, incompatible agents, and unsafe non-symbolic-link entries for manual resolution. With --dry-run, it reports proposed links and schema removal without changing state. Ordinary reads never rewrite configuration.

ki docs [topic]

Print canonical documentation locations without opening a browser, fetching content, or discovering a repository. With no topic, it prints every available location with an explanatory prefix. The supported topics are overview for https://knowledgeislands.info/projects/ki/, site for https://knowledgeislands.info/, manual for https://github.com/knowledgeislands/tools-ki/blob/main/man/ki.1 and roadmap for https://github.com/knowledgeislands/tools-ki/blob/main/ROADMAP.md. Any other topic is invalid command grammar.

ki inventory

List verified installed harnesses and their capabilities with declared user skills and local registered repositories. The command does not fetch, discover a repository, or change state.

ki git check-message <file>

Check the commit message file Git passes to commit-msg against the deterministic ki-git rules, so that a committed .githooks/commit-msg needs no package. Lines from the scissors line onward and every line starting with # are ignored, and the first remaining non-blank line is the header. A header Git generates for a merge, revert, reapply or autosquash commit passes. Otherwise the header must read type(scope)!: subject, with the scope and ! optional; the type must be one of chore, docs, feat, fix, refactor and test; each scope segment, split on / and ,, must be lowercase kebab-case; and the subject must be non-empty with no terminal full stop. A pass prints nothing. A failure exits 1, naming the rule and its reason with a next: line naming the remedy. The command reads no configuration and changes nothing.

ki link <identifier...>

Print one Markdown link per roadmap work-record identifier, such as KI-TOOL-KI-CLI-127, so an owner report or checkpoint links a record in one call. The registered repository whose declared repo_code scopes the identifier is searched first, under docs/roadmap/ or Streams/Roadmap/; with no scope match every registered repository is walked. A live record prints . A record no longer on disk whose number is within its area's high-water mark in _ISSUES.md prints [ (pruned)](/blob//) on the registered canonical repository, where the last revision is the first parent of the newest commit that deleted it. An identifier that resolves to nothing is never given an invented link: the command prints every link it can, then exits 1 naming each reason. It does not fetch or change state.

ki markdown gfm [--root <dir>] [--decisions <file>] (--dry-run [--preview <file>] | --preview <file> --manifest <file>) <path...>

Convert the Obsidian links in the named Markdown files, and the Markdown files under each named directory, to GitHub-flavoured Markdown. Plain and aliased wikilinks, including an alias escaped as | in a table cell, become document-relative links; an unsized image embed becomes a GFM image; and an Obsidian %20 destination is respelled with a space inside angle brackets. A destination holding a space or parenthesis is bracketed, and %, #, ? and angle brackets in a path are percent-encoded. Targets resolve in Obsidian's order against every regular file under the vault root, skipping dot-entries and node_modules: beside the note, then the full path from the root, then a unique path suffix or leaf name, case-insensitively, and the link takes the target's exact on-disk spelling. The root is the nearest directory holding .obsidian or .git, or --root. Everything else is left byte for byte and listed as an item with its line: ambiguous and unresolved targets, heading links unless the decisions file sets heading_fragments = "github", missing headings, block references, sized embeds, transclusions, links in front matter, comments or template expressions, custom or folded callouts, Dataview, and whole files that are protected, generated or not valid UTF-8. Fenced and inline code is never read for links. The decisions file may also list protected paths and, per item, keep it or convert an ambiguous or unresolved link to a named target. --dry-run prints each file's diff, the item list and a summary, and with --preview writes the reviewed preview. An apply re-plans the batch and aborts, writing nothing, unless every file, decision and conversion matches that preview and every item is decided; it then writes the new --manifest holding each changed file's pre-image before it changes any file. The command never formats, and a converted batch converts to itself.

ki mcp install <owner/repository> [version] [--auth github-cli]

Install and activate one governed MCP server source release from GitHub. An explicit version selects only its exact annotated v tag. With no version, public access resolves the latest stable GitHub Release without authentication. Private access requires deliberate --authgithub-cli, which uses the existing GitHub CLI session for release lookup and clone. KI never reads, persists, or displays its credential.

ki mcp update <owner/repository> [version] [--auth github-cli]

Require an existing source installation, build the selected release in same-filesystem staging, and atomically activate it only after provenance, locked dependency installation, build, and entry-point verification succeed. Failure leaves the prior active version unchanged. When authentication is not specified, update retains the active installation's recorded mode.

ki mcp rollback <owner/repository> <version>

Activate one retained complete source version without network access, dependency installation, or build execution.

ki mcp uninstall <owner/repository>

Validate and remove exactly one source installation, including every retained version. This command does not alter MCP client bindings.

ki mcp list [owner/repository] [--format text|json]

List active and retained source versions deterministically. Text marks the active version with *. JSON emits the versioned, path-free ki/mcp-sources/v1 projection with repository, tag, full commit, package version, entry point, installation time, authentication mode, and active state. Source installations live below $KI_DATA_HOME/mcp/; complete versions remain available until explicit uninstall.

ki vscode check

Compare chezmoi-managed VS Code workspaces and trusted-folder source state with the local KI repository registry. Explicit sources bindings join their notes workspace and trusted-client projection; a bound sources folder missing on this host is left out with a warning naming its fix. Legacy bindings and unbound directories are ignored. Preview removal of folder paths that no longer resolve to directories and deletion of projects with no live folders. Existing projects outside the registry and intentionally empty workspaces are preserved. Missing registered checkouts are skipped without changing the registry. Report a source diff and exit non-zero when drift exists. This command never writes.

ki vscode sync [--write]

Preview the same reconciliation. With --write, publish the reviewed changes to chezmoi source state. This command never runs chezmoi apply.

User management

Use these commands to inspect installed capabilities and manage the skills declared in the user-managed KI environment.

ki skill add <skill> [--replace]

Add a registered skill in configured user agent skill spaces.

ki skill remove <skill>

Remove a KI-managed user skill link.

Repository options

Use this shared option with any ki repo command to select one or more repositories. It appears after ki repo and before the command.

--repo <path-or-pattern>

Repeat this option to select literal repository roots or patterns in supplied order. KI resolves every target physically before an operation begins and rejects unmatched patterns, invalid roots, and duplicate physical roots.

-t, --territory <handle>

Select the Capital's declared territory through its territory_prefix, or its registry key when no prefix is declared, or through any of its declared territory_aliases. The registry maps every canonical member identity before filtering. This scope conflicts with --repo, --estate and --principals.

--estate

Select every repository in the registered estate, conflicting with --repo, --territory and --principals.

--principals

Select every registered territory Capital, ranked territories first, then the system Capital and the rest by territory name, conflicting with --repo, --territory and --estate. Without an explicit scope, keep the current repository or direct-CWD .mgit.toml workspace selection. KI does not invoke mgit.

--filter <prefix>

Repeat literal, case-sensitive non-empty directory-name prefixes with OR semantics to narrow any scope, including the native default. Filter before worktree expansion. Missing registration and ambiguous identity fail before filtering, except that territory show and audit report an unregistered member instead; unavailable selected roots or no matches fail before an operation. An excluded registered unavailable checkout does not prevent the remaining operations.

Repository management

Use these commands to inspect and maintain declared capabilities and manage their skill links. Read-only operations isolate per-target diagnostics; a later mutation failure retains earlier successful targets and returns a non-zero result.

ki repo init [directory] --repository <https-url> --capital <https-url> --title <title> --description <description> --repo-code <code> --runtime <runtime>... --visibility <public|private>

Initialize exactly one existing physical Git worktree root. With no directory, it uses the current directory; an explicit directory must be that worktree's root and must not be a symbolic link. Every identity value is required: --title, --description, a stable uppercase --repo-code, canonical HTTPS GitHub --repository, one or more --runtime values selected from claude-code and chatgpt-codex, and --visibility public|private. It atomically creates the minimal canonical ki-repo declaration and A required --capital names the territory Capital; a Capital names itself and then also receives territory_name and territory_members in [skills.ki-repo], listing itself as the first member. Further members must be kept sorted ascending in code-point order; an unsorted list is rejected. registers the physical root in $XDG_STATE_HOME/ki/registry.toml. It never runs git init, guesses identity, activates repository skills, creates a Territory, accepts repository selectors, or overwrites an existing .ki.toml.

ki repo [repo-options] open --target <zed|vscode|delta> [--stores|--no-stores]

Open every selected canonical repository in the requested local target. By default, a Knowledge Base opens its notes root followed by every declared, locally bound external store in declaration order. Each binding must be a direct directory recorded with the canonical repository; it is never made an estate member or territory participant. A store unavailable on this host is skipped with one warning naming its fix, a store marked absent is skipped silently, and the rest still open. --no-stores opens canonical notes roots only, while --stores makes the default explicit. Delta opens repository roots only; it skips stores by default and rejects --stores. Delta's documented project flow stores repository and thread data on its servers even when using a local model.

ki repo [repo-options] audit [--skill <skill>] [--progress <auto|always|never>] [--progress-style <single|multi>] [--reporter-levels <levels|all>] [--staged] [--paths <path...>]

Run the native read-only operations registered by each selected repository's declared capabilities. The host verifies every selected harness inventory and integrity-covered operation before importing it in process; it never dispatches repository-vendored runners. Progress defaults to auto, which follows the output stream's TTY state; always also renders deterministic progress in redirected output, and never suppresses it. On a terminal, progress is a compact receipt stream with one mutable activity row. Its moving bar means work is active; it does not estimate completion from item count or declared cost. Evidence-ready skills appear once with a full bar, then collapse to one timed evidence receipt before rubric results begin. Loading and the operation also finish as timed receipts, with total elapsed time on the operation receipt. Queued skills are not printed. Use --progress-style single to suppress temporary per-skill evidence receipts. Redirected --progress always output defaults to that single-row form. Progress also names the span in which a skill gathers its evidence, before any criterion runs, together with whatever stages and steps that skill reports inside it; a span of unknown extent shows activity and an elapsed clock rather than a completion estimate. Per-skill result rows name the assessed repository first and its supplying harness skill in brackets, and appear only for WARN, FAIL, or FIXED outcomes. Audit renders FAIL and WARN findings by default; --reporter-levels accepts a case-insensitive comma-separated selection from FAIL, WARN, FIXED, INFO, NOT_APPLICABLE, and PASS, or all. A clean repository summary reports PASS with its skill count. Diagnostic counters remain for WARN, FAIL, and FIXED outcomes. --staged and --paths narrow the verdict without narrowing the evaluation: every item still runs against the whole repository and every finding is still rendered, but only a FAIL finding whose subject names a scoped path, a path under a scoped directory, or a directory containing a scoped path makes the audit fail. --staged reads the paths staged in the repository's Git index, deletions included, and fails before auditing when the index cannot be read; --paths takes repository-relative or absolute paths inside the repository and the two combine into one scope. A finding with no subject is outside the scope, and a local registration failure blocks whatever the scope. The frame names the scope, a finding outside it carries (outside scope) after its subject, and the summary leads with the scoped verdict and its SCOPE: counts before the whole-tree counts. A Knowledge Base pre-commit hook uses --staged so a commit is refused only for a finding it causes, while CI keeps the whole-tree verdict. A whole-repository audit, with no --skill, --staged or --paths, records each repository's outcome under $XDG_STATE_HOME/ki/audit-health/: its FAIL and WARN counts, or that it could not complete. ki territory show reads that record as the island's health; a narrowed audit records nothing.

ki repo [repo-options] conform [--skill <skill>] [--dry-run] [--progress <auto|always|never>] [--progress-style <single|multi>] [--reporter-levels <levels|all>]

Stage the same capabilities' safe writes, then apply them and re-audit. All selected initial audits must pass before the staged conform writes are published: a blocking finding aborts before publication, leaving every proposed conform write unapplied. Output labels proposed writes separately from writes applied after that gate; a dry run validates the complete staged write set and reports writes it would apply without changing the repository. This boundary does not include independent local registry updates; it also excludes later selected repositories, subprocess conforms, and rollback after publication has started. Publication refuses unsafe, changed, duplicate, or symbolic-link targets. Conform uses the same progress controls and reporter-level vocabulary as audit, names both the target and supplier for every skill, and renders FAIL, WARN, and FIXED findings by default while retaining every terminal per-skill result. Its second rubric pass is labelled re-audit. When no write or command was staged, conform reports that no re-audit is required and stops after the initial pass. For a local invocation it records each selected canonical root in the machine-local registry before evaluating findings. Registration is an inventory action, not evidence of conformance, so a failing repository remains available for later repair and bulk maintenance. With ki-repo selected, conform creates or replaces both .githooks/pre-commit and .githooks/commit-msg at mode 0755, byte-exact from the resolved harness's canonical ki-repo data for primary_shape and package presence. There is no extension point; repository-specific hook lines are replaced. The dotfiles shape receives no hook changes, and repositories without .ki.toml are not targets. Where hooks are due, the clone's core.hooksPath becomes the literal relative .githooks, replacing foreign and absolute bindings. Bounded Husky retirement remains: prepare retains commands after Husky while binding the hooks; husky leaves the manifest and bun.lock; and .husky/ is removed. Knip's husky.config names both hooks and redundant tool ignores are removed. Unsafe files, unsupported lockfiles and unrecognised package or Knip configurations refuse publication. A dry run reports each planned write, removal and binding and changes nothing.

ki repo [repo-options] roadmap list [--horizon <horizons>] [--status <status>] [--by <grouping>] [--format <text|json>] [--links <compact|all>]

List canonical governed work items from every selected repository without changing their lifecycle. The framed text output names each selected repository, then groups items by lane: open adopted records by horizon now, next, soon, future and hold, then triage intake, then done and cancelled records last. Within a lane, items run from awaiting-review through draft, with identifiers breaking ties. The summary line counts the now lane as a signal with no cap. Records still in the old shape (an initiative, a waiting-for, parked or triage horizon, waiting_on_trades or intake_disposition, or an adopted open record without kind) are listed in the lane they migrate to, marked legacy, and counted as LEGACY; they are tolerated until migration. A component must be declared in [skills.ki-work-roadmap].components. Linked items append one compact provider-qualified task key and a count of additional distinct tickets, preferring implementation links. A legend explains provider abbreviations. Use --links all to replace the suffix with nested task entries showing provider, key, and relation, each with its full URL on a further indented line. Ambiguous keys include authority, scope, and task ID on separate child lines. These options also apply to --aggregate. JSON output stays ki/roadmap/v1 and adds each record's lane, classification, hold, resolution and legacy shapes. Mappings are read locally without contacting task systems and do not imply current task status or ownership. --horizon and --status filter by lane and lifecycle before rendering; unsupported values fail with a usage error rather than an empty result. --horizon accepts a comma-separated list, such as now,next, or a repeated flag, and keeps records in any named lane. --by project groups text output by each record's project across the whole selected set, and implies --aggregate; groups from the same Project in different repositories merge, and a Project from another territory is qualified with that territory's name. Each Project group shows its registry lifecycle, such as [active]. --by theme groups by the theme its Project names in the Capital's Streams/Projects/ notes, with themes read from Streams/Themes/, found through the repository's [skills.ki-repo].capital and the local ki registry; a projectless record groups under its own theme. Records with neither group under unassigned. An unavailable registry, an unknown slug, or a theme that contradicts the registry is a warning that never changes the exit status. Through the work model's tolerance window the thread-model shapes still read, each with a warning naming its new home: Streams/Initiatives/, Project folder notes Streams/Projects//.md, a Project's initiative, the retired Streams/Projects/Initiatives.md index, and a record's initiative, which groups as its theme. A record naming both theme and initiative is invalid. --by area groups by each record's fixed area under the title that [skills.ki-work-roadmap.areas] maps to its code; a legacy bare areas list reads without titles, and JSON output adds areaTitle. --by does not apply to JSON output. The roadmap folder's README.md index is not read as a work item. A KB Streams record field outside the shared record model and the ki-repo-kb note fields is a warning naming the file and field, such as KBS-001-x.md: unknown field owner. The warning never changes the exit status, and JSON output lists it under the repository's warnings. The roadmap adapter still rejects such a field. Both adapters read the optional priority (high, medium or low) and size (s, m, l or xl) fields; any other value, or a ready record of size xl, makes the record unreadable. Within each lane, open records run unblocked first, then by priority with unset as medium, then by size smallest first; priority never crosses lanes, and an aggregate view keeps each repository's records together. Through the field migration window a gaps section names each open record's missing size or kind, retired initiative, theme beside its project, purpose: adoption or retired horizon, in the Harness checker's wording, counted in GAPS= without changing the exit status. JSON items add priority, size and gaps. A missing roadmap directory or malformed or unsafe item is an isolated diagnostic for that repository; other selected repositories still report, and any roadmap or trade diagnostic makes the command exit with status 1 after rendering the inventory. The command never creates, transitions, accepts, prunes, or repairs a work item.

ki repo [repo-options] roadmap summary [--by <grouping>]

Show selected repositories as rows against lane columns. Each cell shows nonzero lifecycle-status counts and a sum, such as d=1 r=2 Σ=3. The Σ column and row aggregate the same counts per repository and per lane. A legend expands t (triage), d (draft), r (ready), ip (in-progress), ar (awaiting-review), x (done), and c (cancelled). A dash means no items in that cell; a question mark means unavailable. Repositories without a roadmap are named below the table. Invalid roadmap evidence remains diagnostic and makes the command exit with status 1. Item identifiers, titles, and trade records are omitted. --by project, --by theme or --by area replaces the repository rows with one row per group, aggregated across the selected set as for roadmap list --by, and appends any grouping warnings. Unknown KB Streams record fields are listed under the same warnings.

ki repo [repo-options] roadmap stats [--stale-after <duration>] [--format <text|json>]

Report age and inactivity metrics for selected local roadmaps. Every valid work item requires paired canonical UTC-second creation and update timestamps; timestamp-free records are diagnostics, not compatibility records. The NOT_DONE count includes every open item, including triage records, and excludes done and cancelled ones. Multiple selected repositories add a selected-set aggregate. A positive stale duration uses seconds, minutes, hours, or days, such as 7d. Use --format json for a versioned machine-readable report.

ki repo [repo-options] roadmap prune [id] [--no-commit] [--dry-run]

Without an ID, delete every canonical work-item record whose lifecycle status is done or cancelled from the selected repositories. It leaves every open lifecycle status, non-canonical file, and peer repository untouched. If no selected repository contains a terminal record, it reports that no record was pruned. With an ID, require exactly one selected repository and delete only that named done or cancelled record. By default, each repository with pruned records gets one commit that contains exactly those deletions, with the subject chore(roadmap): prune done work record(s) whichever terminal state the records reached, and one - body line per record; commit hooks run. Before deleting anything, the command refuses when a selected repository is not a Git work tree, has staged changes, or holds a selected record that is untracked or modified, so each record's terminal state is committed before the prune commit. A failed commit restores that repository's records, and a commit that a hook widened with other paths is reported as an error. --no-commit only deletes the records and skips the Git checks. --dry-run makes the same selection and checks, then reports the records and planned commits without deleting or committing.

ki repo [repo-options] roadmap promote <id> [horizon]

Move exactly one selected repository's named work item one horizon toward now along now, next, soon, future and hold. With an optional destination horizon, move directly only toward now; the current horizon, a hold-facing destination, and the now endpoint are errors. Leaving hold re-decides the horizon, so it requires a named destination and removes the record's hold mapping. Triage records are adopted through the planning workflow, done and cancelled records have no horizon, and records still at a legacy horizon must be migrated first. The destination must be allowed for the record's status: ready records stay within now, next and hold, and in-progress and awaiting-review records within now and hold. The command changes only the item's horizon frontmatter and its update timestamp.

ki repo [repo-options] roadmap demote <id> [horizon] [--reason <reason>] [--condition <text>] [--review <date>]

Move exactly one selected repository's named work item one horizon toward hold. With an optional destination horizon, move directly only toward hold; the current horizon, a now-facing destination, and the hold endpoint are errors. A move into hold requires --reason (waiting-for or parked) and a --condition naming the release condition, with an optional ISO --review date; these options are rejected for any other destination. The same lifecycle and status rules as promote apply.

ki repo [repo-options] roadmap migrate [--apply]

Preview the mechanical roadmap model migration for every selected repository, printing each changed record's removed and added frontmatter lines and the review notes it needs. The pass moves a triage horizon on a draft to status: triage; a waiting-for or parked horizon on an open record to horizon: hold with a hold reason and a condition lifted from the record prose, or a REVIEW placeholder when none is found; waiting_on_trades to hold.trades; and a done Triage intake disposition to status: cancelled with its resolution and any resolution_target, noting that a Cancelled section is still needed. It advances updated_at, never touches theme, kind, project, or purpose, and a migrated record needs no further mechanical change, so a second run reports nothing. --apply writes the records in exactly one selected repository whose roadmap has no unreadable record, and never stages or commits. Unreadable records are diagnostics that make the command exit with status 1.

ki repo [repo-options] store list [--format <text|json>]

List every store role declared by selected Knowledge Bases. The notes role is the repository root; external roles show their explicit machine-local path or unbound state and their availability on this host: a bound store is available or unavailable, with its reason, and an unbound one is absent by choice or missing. Unavailable and missing stores name their fix: the bind command, with the path filled in when exactly one conventional sources- folder exists, or the absent command. A folder the host refuses to read is unavailable with access denied and its fix, never missing: on macOS, grant Full Disk Access to the terminal app, or to sshd-keygen-wrapper over SSH, or run ki at the Mac's screen. A denied conventional folder is not offered as a fix. Repository selection is given to ki repo, before store. JSON emits the versioned ki/repository-stores/v1 contract, whose state stays bound or unbound and which adds availability and reason.

ki repo [repo-options] store scan

Inspect selected repositories for direct conventional OneDrive sources- directories without a matching declared sources store role. Warnings identify the repository kind and an explicit decision to declare and bind, migrate to a Knowledge Base, or retire the directory; warnings exit successfully. Unsafe paths or unreadable repository declarations remain diagnostics and cause a non-zero exit. A territory Capital is checked under both its canonical handle and its historical basename, and malformed Capital territory metadata is a diagnostic. Repository selection follows normal ki repo semantics, including --estate for every registered repository. The command never creates, binds, moves, or removes a directory.

ki repo [repo-options] store create sources [--write]

Preview the conventional opt-in OneDrive sources- directory and registry binding. The name is the repository basename, or a territory Capital's canonical handle: its territory_prefix, else its registry key. A Capital with neither fails. With --write, create and bind it. Automatic creation is unavailable for legacy. Where the OneDrive root does not exist, as off macOS, it refuses and names the two remaining routes: bind an existing directory, or mark the store absent on this host. A denied OneDrive root refuses with the denial.

ki repo [repo-options] store bind <sources|legacy> <absolute-path> [--write]

Preview an explicit binding for one declared external store. The path must be an existing absolute directory, not a symbolic link; a denied folder is refused. The preview names the registry file it would write. With --write, publish the binding to the machine-local registry, clearing any absence marker for the role, and print the undo: unbind command.

ki repo [repo-options] store unbind <sources|legacy> [--write]

Preview removal of one declared external-store binding. With --write, publish the registry change without deleting or modifying store content. An absence marker is left unchanged.

ki repo [repo-options] store absent <sources|legacy> [--clear] [--write]

Preview recording, in the machine-local registry entry's absent_stores, that this host deliberately does without one declared external store. A marked store is reported once as information and draws no warning. A bound role is refused until it is unbound; notes is refused. --clear removes the marker. With --write, publish the change.

ki repo [repo-options] educate [--skill <skill>]

Explain each selected repository's declared capabilities and their recommended maintenance actions without changing repository state.

ki repo [repo-options] diag

Report each selected repository's declared skills and compatible runtime projection health without changing repository or registry state. It returns a non-zero status when a declaration or projection is unrepairable.

ki repo [repo-options] repair [--dry-run]

Record each selected physical repository root in the local user register, then reconcile only missing, dangling, or stale KI-managed compatible projections. It never creates a declaration, adds an undeclared skill, overwrites foreign content, guesses a provider or runtime, or follows a symbolic declaration. A Knowledge Base's declared external store that is unavailable on this host is a warning naming its fix, and one marked absent is reported as information; neither fails the repair. The command writes by default. --dry-run reports the same actions without creating state directories or changing disk state. Store mutations and VS Code sync instead preview by default and require --write.

ki repo [repo-options] skill add <skill> [--replace]

Add a registered skill in each selected repository.

ki repo [repo-options] skill remove <skill>

Remove a KI-managed repository skill link and declaration from each selected repository.

ki repo [repo-options] upgrade

Refresh uniquely resolved harness providers declared by each selected KI repository. It changes neither user nor repository skill activation.

Batch records

Use these commands to maintain one already-approved exact set of Ready local work records. They validate and record caller-supplied authority evidence; they do not select work, execute an agent, accept delivery, prune work, push, or release.

ki repo [repo-options] batch prepare --item <id> [--item <id>...] --approved --authority-mode <reviewed-items|outcome> --expires-at <timestamp> --completion-target <awaiting-review|done> [--authority-evidence <text>]

Create one current canonical exact-set batch authority record from explicit approval evidence and Ready work items in dependency order.

ki repo [repo-options] batch validate <record>

Validate an open batch against live canonical work records and its expiry. A closed batch validates its named outcomes against the immutable close-evidence commit, so later legitimate pruning does not erase the delivery proof.

ki repo [repo-options] batch run <record> [--item <id> --result <awaiting-review|done|parked|stopped> --baseline <commit|—> [--result-commit <commit>] [--exception <text>]]

Start the derived run or append one explicit caller-supplied item result without executing work or changing roadmap lifecycle.

ki repo [repo-options] batch close <record> --completion-target <awaiting-review|done> --evidence-commit <commit>

Append structural closure evidence only after every named live item and the exact evidence commit contain the approved all-item target in valid dependency order.

Knowledge Base search

Index and search one explicitly registered Knowledge Base with scoped local citations.

ki kb index [--kb <id>] [--daemon-url <origin>]

Build a fresh private qmd generation for one explicitly assigned registry KB.

ki kb search <query> [--kb <id>] [--mode <query|search|vsearch>] [--limit <count>] [--zone <name>] [--path-prefix <path>]

Return bounded current-source-authenticated JSON results without silent fallback.

ki kb status [--kb <id>]

Report configured mapping and loopback endpoint reachability; health does not attest index identity.

Registry management

Use these root-level commands to record and list canonical KI repository roots in $XDG_STATE_HOME/ki/registry.toml. Registry membership is an inventory, not a repository-operation or conformance verdict. The repository key names each record; each record holds a canonical HTTPS GitHub repository identity and physical checkout path.

ki registry [--repo <path-or-pattern>]... [-t|--territory <handle>] [--estate] [--principals] [--filter <prefix>]... add [--dry-run] [--search-boundary <id>]

Record selected canonical KI repository roots in $XDG_STATE_HOME/ki/registry.toml without applying repository repairs. This explicit inventory action validates the selected root's declared canonical identity and preserves existing entries. It never searches outside the supplied target selection. The command writes by default; --dry-run reports proposed registration without creating the state directory or changing disk state.

ki registry list [--format <text|json>]

List physical KI repository roots explicitly registered in the machine-local registry, one absolute path per line. The command neither discovers repositories nor changes state. With --format json, emit the versioned path-free ki/registry/v1 contract with canonical identity and declared repository metadata, including repoType as project or kb for available repositories and null for unavailable ones. An unavailable declaration remains represented without a local path and makes the command exit non-zero.

ki registry remove <key> [--dry-run]

Remove exactly one complete registry entry by its local key. The command reports the removed key, repository identity, and stored path, and leaves every other entry unchanged.

ki registry --repo <path> remove [--dry-run]

Remove exactly one complete registry entry by its stored path, including when the checkout no longer exists. Removal rejects bulk selectors and publishes the validated replacement atomically. Use --dry-run to inspect the write without changing registry state.

Harness management

Use these commands to install, inspect, and remove compatible harness payloads in the user-managed KI environment. A configured private GitHub archive may declare auth = github-cli only with its matching commit-pinned https://codeload.github.com///tar.gz/ URL. KI obtains the credential through gh auth token and sends it only on that no-redirect archive request; it neither stores nor prints the token. Authenticate the GitHub CLI first with gh auth login.

ki harness info <harness-id>

Inspect one user-installed compatible harness and its capability inventory without changing user state.

ki harness list

List compatible harnesses already installed.

ki harness install <harness-id>

Install a harness from which capabilities, such as skills and subagents, can be added.

ki harness reinstall <harness-id>

Replace one inactive installed Harness with a verified archive. The command refuses a Harness that supplies active user skills. A development-linked Harness must first be restored with ki dev local off .

ki harness uninstall <harness-id>

Remove one non-canonical harness with only recognised payload directories. The canonical harness cannot be removed, and a harness that supplies active user skills cannot be removed. A successful removal deletes its identifier from [harnesses].ids.

Trades

Use these commands with repositories that declare the portable ki-repo-trades capability and are present in the local registered repository estate. Routes and standing grants come only from the territory Capital's [skills.ki-trades.territory] policy, resolved through each repository's declared [skills.ki-repo].capital; no command edits that policy, and a member declaration carries no route table. Parent --repo, --territory, --estate and --principals selectors scope reads; mutations require exactly one selected registered repository. Every mutation writes only the selected repository, a granted route gives visibility rather than acceptance or retention, and no command changes a peer roadmap or knowledge. A repository that declares ki-trades but whose Capital does not resolve is never dropped silently. Aggregate routes list and trade list views, and policy compare, print skipped: () for it and add SKIPPED=n to the summary; under --format json, and for trade show, the line is written to standard error so standard output is unchanged. Selected alone, such a repository fails closed with the reason.

ki repo [repo-options] trade routes list [--incomplete] [--format text|json]

List selected local typed routes with their registered-estate state. With a parent aggregate selection such as ki repo --estate trade routes list, list valid selected repository declarations as lexical repository pairs. The left and right endpoint cells span the two directional rows, which show what each repository sends with a right or left arrow; a missing direction is shown as an em dash. The table adapts to the live terminal width, preserving the same pairs in a stacked narrow view. With --incomplete, show only routes that await reciprocity or have ambiguous peers. With --format json, emit the versioned ki/trade-routes/v1 contract. JSON requires an aggregate parent repository selection. It contains canonical identities, route evidence, peer resolution, and declared map bonuses without local registry paths, declaration paths, or presentation layout values. Text remains the default renderer. Interactive visualisation is owned by Knowledge Islands Observatory rather than this command.

ki repo [repo-options] trade routes check [repository] [--direction export|import] [--kind work|knowledge]

Check the routes the territory Capital policy grants this repository. A route is active when its peer is registered once, declares ki-trades, and resolves the same Capital; otherwise an export awaits the receiver and an import awaits the sender.

ki repo [repo-options] trade policy show

Show the trade policy of the selected repository's territory Capital: its channels, standing grants, and knowledge subtype vocabulary. The policy is resolved through the repository's declared [skills.ki-repo].capital; an unregistered Capital fails with territory policy lives in , not available here.

ki repo [repo-options] trade policy check

Sweep the selected repository's territory through the local registry. Each listed member is reported conforming, warning (declares ki-trades but no channel names it), failing (registered twice, invalid, declaring another Capital, or named by a channel without declaring ki-trades), or unverifiable (not checked out here). A registered repository that claims the Capital without being listed also fails. Any failure exits 1 after rendering.

ki repo [repo-options] trade policy compare --baseline <path>

Compare the active directed routes of a saved ki/trade-routes/v1 report with the routes the current registry and Capital policies make active, listing lost and newly granted routes. The current side always sweeps the whole local registry, whatever the parent repository selection. A baseline route lacking string source and peer repositories, an export or import direction, or a known trade kind is rejected as malformed. A lost route exits 1 after rendering.

ki repo [repo-options] trade standing list [--incomplete]

List the standing grants the territory Capital policy gives this repository. A grant is active exactly when its ordinary knowledge route is active. With --incomplete, show only grants that are not active.

ki repo [repo-options] trade standing check [repository] [--direction export|import] [--subtype <subtype>]

Check all Capital-granted standing grants or select one repository, direction, and subtype.

ki repo [repo-options] trade standing capture <repository> --subtype <subtype> --source-ref <commit:path#anchor> --capture <path#anchor>

From the receiver repository, append one marked ki-trades/standing-intake/v1 TOML provenance block to an existing local Markdown file. The command requires an active exact standing import, a full source commit, and a source path that resolves in the locally registered source checkout. It never writes to the source repository. Standing intake grants no roadmap, publication, implementation, acceptance, completion, Territory, or peer-write authority; use an itemized knowledge trade when the exact standing contract does not fit.

ki repo [repo-options] trade prepare <repository> --kind work|knowledge --observation unattended|receipt|decision|completion --title <title> --source-ref <reference> --context <text> --submission <text> --constraints <text>

Create one mutable preparation in the current repository when it declares the matching export route. The mandatory observation policy selects whether receipt, a terminal decision, or completion of adopted work is required before release; unattended requires no receiver follow-up beyond an observable receipt.

ki repo [repo-options] trade observe <trade-id>

Read one sender's committed mutable preparation without receiving or acting on it. Compare it with the commit last observed by this receiver, or show the full current contents when no usable earlier Git evidence exists.

ki repo [repo-options] trade submit <trade-id>

Freeze one local preparation and move it to the outbound submitted path.

ki repo [repo-options] trade abandon <trade-id> --yes

Remove one unsubmitted mutable preparation after explicit confirmation.

ki repo [repo-options] trade receive <trade-id> | --all [--yes]

Import one committed outbound submission into the current repository and record its source commit. The --all form previews every receivable submission and changes nothing unless --yes is also supplied.

ki repo [repo-options] trade list [--direction prepare|import|export] [--status <status>] [--kind work|knowledge]

Read visible preparations, imports, and exports in selected repositories, including each selected receiver's imports awaiting receipt. The parent --estate selector combines all registered repository views. Each record reports its observation policy, delivery and decision state, and cleanup eligibility. An unsupported --status decision value fails with a usage error.

ki repo [repo-options] trade show <trade-id>

Show selected visible copies of a trade; use parent --estate to inspect all registered copies.

ki repo [repo-options] trade release <trade-id> | --eligible [--yes]

Remove one current-repository outbound submission only after its observation policy is satisfied. The --eligible form previews all eligible submissions and changes nothing unless --yes is also supplied.

ki repo [repo-options] trade prune <trade-id> | --eligible [--yes]

Remove one eligible current-repository inbound copy only after sender release is observable. The --eligible form previews all eligible copies and changes nothing unless --yes is also supplied.

Territory management

Territories derive membership from registered Capital declarations. Use the Capital's territory_prefix handle, or its registry key when no prefix exists; a declared territory_aliases entry selects the same territory. Exactly one of --territory, --estate and --principals is required for scoped commands. --principals selects only the registered Capitals: first the system Capital, whose territory includes knowledgeislands/ki-agentic-harness, then the rest by territory name. A territories.ranking list of handles in config.toml puts ranked territories first, in that order, for --principals, territory list and --estate; the estate groups roots by their ranked territory. Repeated --filter values match directory basenames literally and case-sensitively.

ki territory list

List registered territory handles, titles, Capitals and declared member counts, in territory order.

ki territory audit (--territory <handle>|--estate|--principals) [--filter <prefix>]...

Validate the complete selection and its physical checkouts without mutation.

ki territory inspect (--territory <handle>|--estate|--principals) [--filter <prefix>]... --target <zed|vscode> --workspace <selector>

Compare selected roots with one explicit local editor projection. Exit 0 for exact state, 1 for drift or unsupported source, and 2 for invalid selection.

ki territory show (--territory <handle>|--estate|--principals) [--filter <prefix>]... [--verbose] [--format <text|json>]

Show selected repositories with their declared maturity and recorded audit health, optionally with identities, paths and evidence, as text or ki/territory/v1 JSON.

ki territory roots (--territory <handle>|--estate|--principals) [--filter <prefix>]... [--null]

Write deterministic absolute primary checkout roots. Use --null or -0 for NUL termination. Validate the complete selection before writing any stdout bytes.

ki territory open (--territory <handle>|--estate|--principals) [--filter <prefix>]... --target <zed|vscode|delta>

Open the selected repositories through an explicit existing local adapter. Each target's project list follows the selection order; Zed, which prepends each folder, is opened in reverse.

Acquisition

Acquisition is action-first and adapter-driven. Installed Harness skills publish verified machine-readable adapter declarations; repository configuration enables them.

ki acquire images

--adapter granola [--repo ] --source --directory --expected [--dry-run] Verify UUID-named image exports from the Granola desktop app against an already acquired meeting. Preserve their exact bytes and a checksum manifest beside its Markdown in the receiving Knowledge Base. The expected count is observed in the desktop Images stack, not supplied by Granola MCP.

ki acquire list [--repo <path>]

List enabled, available, and invalid acquisition adapters with owning skill, actions, configuration, executable status, and activation guidance.

ki acquire import [--adapter <name>|--all] [--repo <path>] [--since <date>] [--until <date>] [--dry-run]

Run one selected adapter, every applicable enabled adapter, or infer the sole enabled adapter. Adapter-specific invocation properties require explicit --adapter. ChatGPT accepts --capture and --output. Granola accepts --refresh and --refresh-acquired.

ki acquire mark

--adapter granola [--repo ] [--since ] [--until ] [--source <UUID...>] [--confirm] Preview notes eligible for the configured private Acquired folder. With --confirm add only that membership after verifying committed local captures, complete transcripts, fresh source hashes, and screenshot UUIDs and bytes. Preserve all original folders and read back the result. Exceptions remain unmarked. A progress marker grants no source retirement or reconciliation authority. Granola import uses only allowlisted read-only MCP operations. It enumerates complete global and folder identity evidence and keeps no acquisition ledger, checkpoint or journal: the committed capture is the record. Meetings in the configured Acquired folder are skipped on membership alone. Each new meeting is written to its folder-mapped capture path, and an existing capture, found by its UUID wherever it has been filed, is never overwritten unless --refresh is given; a refresh rewrites it in place and keeps a transcript the provider no longer returns. By default it stages meeting Markdown beneath +/_ACQUIRE/granola/. A configured capture_root and complete folder_territories table receive several folders as one package per meeting UUID, retaining every membership. The unfoldered and residual selectors also accept "flag", which reports identities without reading their details or transcripts; unmatched live folders are reported even when empty. Multiple territories or unmapped folder memberships require review. MCP screenshots are decoded, identity-checked and retained as exact returned bytes with checksum manifests, including verified zero-image inventories. A configured acquired_folder_id is progress metadata distinct from routing. --refresh-acquired deliberately reads marked notes again and implies --refresh. Conflicting receiver mappings fail closed. Only the separate confirmed mark action adds membership; import never mutates Granola. No action edits notes, removes folders, archives, deletes, or switches accounts or workspaces.

Background agents

Launch and coordinate detached background agents under the ki-delegation background-run contract. A run's runtime files live in $KI_STATE_HOME/agents//: a prompt, one-line status, pid, and log per agent, the queue, and thread.json, which records the run's work folder. Its knowledge files, the decisions.md log and each agent's .report.md, live in the owning repository's tracked work folder +/_WORK//, so the state folder can go without losing them. An agent writes its report to .report.md in the state folder, and the first command that sees its DONE copies the report into the tracked folder, unless the folder holds a copy with changes Git does not hold. ki is their only writer, so no thread copies them by hand, and never commits them; the thread commits them with its other work. The first launch, queue, new or decide for a run fixes the home as the Git top level of the working directory, or of --repo