The home of ki, the Knowledge Islands command-line interface (CLI).
tools-ki is the canonical source of the ki executable platform. It installs verified compatible harnesses, resolves repositories, activates skills in explicit user or repository scope, and hosts registered native operations. It consumes reusable agentic capabilities from the KI Agentic Harness, does not define their standards, and supplies implementation evidence that KI Specifications may formalise as portable contracts.
Arcadia Principal remains the source of Knowledge Islands philosophy and model, and Techne Principal translates that philosophy into engineering practice. The KI Website may vendor source-labelled CLI material for public publication, while this repository remains canonical for the executable and its release artifacts. The mirrored ecosystem decision defines the six authorities and publication flows.
The active TypeScript command host provides local capability, repository, Agora, and trade operations, plus an action-first, provider-neutral ki acquire surface backed by verified Harness adapter declarations. The sections below describe the current public surface; use ki --help or the tracked ki(1) manual for exact grammar.
If ki is not yet installed, read install ki and run it for the first time. It covers installing a signed release, creating the user environment with ki bootstrap, registering a repository, and verifying each step. The rest of the user guides carry the procedures for everything described below.
Assemble a capture directory in the controlled ki-chatgpt-capture format, then import it into a new output directory:
ki acquire import --adapter chatgpt --capture ./capture --output ./conversation.kepUse --dry-run to validate without creating output. The command is local only: it does not contact ChatGPT, automate a browser, read credentials, discover repositories, or extract knowledge. The capture layout, its metadata fields, and the validation failures you may hit are documented in import a local ChatGPT capture.
With the official Granola MCP configured as granola in mcporter, inspect and acquire complete selected history into the current registered repository's Harbour:
ki acquire list
ki acquire import --adapter granola --since 2023-01-01Use --repo /path/to/repository to select another eligible receiver and --dry-run to perform all reads and verification without writing. Routine acquisition revalidates mutable meeting detail, reuses verified transcripts, journals interrupted work, stages one Markdown document per selected identity, and advances its receiver-local checkpoint only after complete verification. It never mutates Granola or writes another repository. Adapter activation, receiver selectors, transcript refresh, disposition, reset, and interrupted-import recovery are documented in Acquire Granola meetings.
ki harness install, ki harness reinstall, and ki harness uninstall manage verified harness payloads without activating or deactivating skills.
Use a harness identifier such as example/harness.
A compatible Harness declares its stable capability namespace in its root .ki.toml, for example [skills.ki-repo-harness] with prefix = "ki". Every published skill uses that prefix (ki-*), and ki refuses a second installed Harness claiming it. Distinct prefixes such as ki and hnr coexist; competing Harnesses using the same prefix do not.
An immutable private GitHub harness archive may opt into the local GitHub CLI credential without placing a token in configuration, by declaring auth = "github-cli" alongside its commit-pinned codeload URL and SHA-256.
Install harnesses and activate their skills covers the installation-versus-activation boundary, the user and repository activation scopes, the private-archive declaration in full, and the refusals that protect an active capability from being removed underneath it.
ki manage update refreshes installed harnesses with configured immutable releases and updates the executable only when a verified installer receipt proves that it owns the running regular installation.
ki manage completion bash and ki manage completion zsh print corresponding completion source derived from the registered CLI tree, so the completions cover every command path and valid option name without a second list to maintain.
ki repo upgrade refreshes the uniquely resolved providers declared by one or more selected KI repositories.
Neither command changes user or repository skill activation. Maintain a local installation covers update ownership, shell completion, diagnosis, and repair.
An Agora is declared portably by a registered owner repository under [skills.ki-agora.homes.<id>]. Each home names its own canonical repository identity, which ki verifies against the local registry and includes in the resolved projection. Its other declared members reciprocate under [skills.ki-agora.memberships.<id>]; ki resolves the declaration only when every member is also locally registered and agrees with its owner and role. A home may declare order as a duplicate-free prefix of those canonical participant identities.
estate is the reserved system selector for every locally registered canonical KI repository. Use ki agora list, ki agora show <id>, and ki agora open <id> --target zed to inspect or open a declared Agora or the estate. Opening requires an explicit permitted target; supported local-client adapters are zed and vscode.
ki agora audit [id] checks declaration and reciprocal-membership health without modifying the repository estate. With no identifier it reports every declared profile; a named profile or estate limits the report. Exit status is 0 for healthy selections, 1 when findings are reported, and 2 for invalid or unknown explicit selectors.
ki agora inspect <id> --target <zed|vscode> --workspace <selector> compares one explicitly selected local editor workspace with the canonical resolved Agora. VS Code selectors are absolute physical .code-workspace files; Zed selectors are decimal workspace IDs resolved from the local stable or preview database. The command is read-only, reports matched, missing, extra registered, unregistered KI, and external roots, then exits 0 for an exact projection, 1 for drift or an unsupported source, and 2 for invalid selection or resolution.
ki agora roots <id> is the versioned machine interface for a resolved group's physical roots. A named Agora places its declared order prefix first and appends unlisted participants in registry-key order; an Agora without order and the system estate retain registry-key order throughout. The command writes newline-delimited absolute roots; use --null (or -0) for safe NUL-delimited path handling. It fails before writing any root when the selector cannot resolve or has no members, and it never clones, repairs, or treats source or legacy stores as Agora members.
An Agora owner may include ordinary Git repositories in its portable references list without making them KI members. Associate one explicit local checkout with ki agora reference set <repository> <absolute-checkout>, inspect associations with ki agora reference list, and remove one with ki agora reference remove <repository>. ki validates the checkout root and canonical origin identity without requiring .ki.toml, stores only machine-local state, and never clones or mutates the referenced repository. Unresolved references remain typed diagnostics and are omitted from projected roots without affecting reciprocal owner or member resolution. See the Agora reference guide for setup and recovery.
Every ki repo operation accepts repeated --repo <path-or-pattern> options, one --agora <name> option, or --estate as shorthand for --agora estate. The three explicit selectors are mutually exclusive. Literal paths and patterns resolve to physical KI repository roots in deterministic order; an unmatched pattern, invalid root, or duplicate root stops the operation before any target runs.
ki repo --agora <name> selects registered owner-declared member repositories (or estate) and requires each selected root to remain a physical KI repository. A repeated declaration id is rejected with every declaring owner so the user can resolve the ambiguity. Without an explicit selector, ki reads a regular direct-CWD .mgit.toml schema-one manifest. Workspace manifests select their configured group, recurse through child workspaces, use structural member types for standard and nested main/ checkouts, and skip bare stores. Repository manifests fall through to ordinary single-repository discovery. ki never invokes mgit. Selection never resolves to no repository: a selector that matches nothing fails with an actionable non-zero exit rather than completing an operation over nothing.
Existing physical mGit members without .ki.toml are skipped; ki repo audit names them in normal and concise output. Missing or unsafe checkouts, unsafe or invalid KI declarations, and a selection with no KI repositories fail.
After target selection, operations run in target order. Read-only operations isolate a target's diagnostic; mutations retain earlier successful targets if a later target fails and return a non-zero overall result. The machine-local registry is $XDG_STATE_HOME/ki/registry.toml; every keyed entry holds a canonical HTTPS GitHub identity and checkout path. Use ki registry add --repo <path-or-pattern> to record selected canonical KI roots without applying repairs. ki bootstrap --refresh imports the retired configuration path list once and removes it from user configuration. A local ki repo conform also records each selected root first, even when its later conformance checks fail, so the registry remains an inventory for repair and bulk maintenance rather than a compliance badge.
schema = 1
[repositories."ki-agentic-harness"]
repository = "https://github.com/knowledgeislands/ki-agentic-harness"
path = "/Users/example/workspaces/knowledgeislands/ki-agentic-harness"For each selected repository, ki repo conform collects safe write proposals and completes every initial audit before publishing any of those proposals. A failing initial audit aborts that repository's conform publication: no proposed conform write is applied. On a terminal, audit and conform use a compact receipt stream with one mutable activity row that signals activity without estimating completion.
Audit and conform repositories covers target selection, reading an audit result, the exact meaning of conform's proposed write, applied write, and would apply write verbs, what the publication boundary does not cover, the output and progress controls, and repair.
To start a KI repository, run ki repo init in an existing Git worktree root, or name that root as its one argument. Supply its canonical --repository https://github.com/<owner>/<name>, --title, --description, --repo-code, one or more --runtime values (claude-code or chatgpt-codex), and --visibility public|private. Initialization declares a Project with repo_type = "project", primary_shape = "ki-repo-project", and the baseline shape skill, then registers that physical root locally; it never runs git init, guesses identity, activates skills, creates an Agora, or overwrites an existing declaration.
Every [skills.ki-repo] declaration requires an explicit repo_type and primary_shape. The shape must name a declared core Project shape, or ki-repo-kb when repo_type = "kb". Specialist and refining skills remain composable; their presence does not choose or change the primary shape. The ki-repo skill owns the allowed shapes and compatibility rules.
ki agora list
ki agora audit
ki agora audit estate
ki agora inspect estate --target vscode --workspace "$PWD/knowledge-islands.code-workspace"
ki agora show estate
ki agora roots estate | xargs -n 1 sh -c 'git -C "$1" status --short' _
ki agora roots estate --null | xargs -0 -n 1 sh -c 'git -C "$1" status --short' _
ki agora open estate --target zed
ki repo init --repository https://github.com/example/example --title 'Example repository' --description 'An explicit KI repository identity.' --repo-code EXAMPLE --runtime claude-code --runtime chatgpt-codex --visibility private
ki manage diag
ki repo diag
ki repo repair --dry-run
ki repo --agora estate auditki batch prepare, validate, run, and close provide deterministic local file mechanics for an already-approved exact set of Ready roadmap items. The commands protect the authority payload, bind a run, append explicit item evidence, and require every named item to match the approved completion target before recording closure. They do not select or implement work, infer approval, change roadmap lifecycle, accept or prune items, push, or release.
ki batch prepare --item KI-EXAMPLE-001 --item KI-EXAMPLE-002 --approved \
--authority-mode reviewed-items --expires-at 2099-01-01T18:00:00Z \
--completion-target awaiting-review
ki batch validate KI-EXAMPLE-BATCH-001
ki batch run KI-EXAMPLE-BATCH-001Replace the illustrative identifiers and expiry with the approved Ready items and active window for the selected repository.
See canonical batch records for result and close examples, retained-record handling, and the process-authority boundary.
ki repo roadmap list --format json emits the versioned, path-free ki/roadmap/v1 projection with canonical record URLs for integrations.
Linked roadmap items show one compact ticket reference after the title, such as PC:KIS-42 +2, with a legend for provider abbreviations. The count covers additional distinct tickets; implementation links take precedence. Use ki repo roadmap list --links all to expand every mapping beneath its item, with the provider, ticket key, relation, and full task URL on a further indented line. Matching keys are qualified when needed. Both views use local mappings without contacting ticket systems; links do not imply current task status or ownership.
ki repo roadmap list reads the canonical work-item records in selected repositories without changing them. A selected repository without its declared roadmap directory contributes no roadmap and does not make the list fail; malformed, unsafe, unreadable, or misconfigured roadmap evidence remains a diagnostic and returns status 1.
Its default deterministic text output uses the same framed grouping style as repository audits: each repository has a header, nested horizon and lifecycle branches, its import and export trade context, diagnostics, and a compact summary. Use --aggregate for one selected-set inventory grouped by local horizon; item identifiers carry the repository-aligned prefix, while no-roadmap and diagnostic sections name their repositories. It is a scanning view, not a cross-repository priority queue. Unadopted triage intake remains visible, but generic promote and demote operations do not adopt it. Use --horizon <value> or --status <value> to filter records before rendering.
ki repo roadmap stats reports active count, median and maximum age and inactivity, plus a selected-set aggregate when multiple repositories are selected. Text output renders compact compound durations such as 1d 2h 3m 4s; --format json retains exact numeric seconds in the versioned automation contract. --stale-after <positive-duration> accepts seconds, minutes, hours, or days such as 7d.
Malformed or unsafe work items become a diagnostic for only that selected repository, while other selected repositories still report; any such diagnostic makes the command exit with status 1.
ki repo roadmap prune [id] removes every canonical done record in the selected repository set when no ID is supplied. With an ID, it requires exactly one selected repository and removes only that named done record. ki repo roadmap promote <id> [horizon] and ki repo roadmap demote <id> [horizon] move one explicitly named item one horizon toward now or future, respectively; an optional destination permits a direct move only in that direction. These operations change only the canonical work-item file and preserve lifecycle status.
Creation, shaping, readiness, implementation, acceptance, and completion remain harness-process and human-authority operations. The native commands do not infer those judgments from a trade or alter a peer repository.
ki trade routes list presents the current repository's declared export and import routes in a framed tree, including their registered-estate state. ki trade routes list --estate presents every registered repository's valid route declarations as lexical repository pairs: the left and right endpoint cells span two directional rows, with → and ← showing what each side sends; an absent direction is explicit as —. The table adapts to the live terminal width, using the same pair model in a stacked view when it is narrow. --incomplete focuses either inventory on routes awaiting reciprocity or with ambiguous peers. ki trade routes list --estate --format json emits the versioned ki/trade-routes/v1 contract for applications such as Knowledge Islands Observatory. It contains validated canonical identities, route evidence, resolution, and bounded map bonuses, but no registry paths, declaration paths, or presentation-derived layout weights. A route cannot be removed while a preparation, submission, or received copy still depends on it.
ki trade prepare creates a mutable sender-local preparation with a mandatory observation policy: unattended, receipt, decision, or completion. A receiver with the reciprocal route may use ki trade observe to compare the sender's committed preparation with the commit it last observed; this does not receive or act on the preparation. ki trade submit freezes the preparation as an outbound record, while ki trade abandon --yes removes an unsubmitted preparation.
ki trade receive <trade-id> imports one committed submission and records its source commit. ki trade receive --all previews every receivable trade and changes nothing until --yes is also supplied. Receiver-owned decision evidence remains local; the sender-owned envelope and body are immutable.
ki trade subtypes maintains receiver-owned knowledge subtype definitions. ki trade standing adds, lists, checks, and removes exact reciprocal standing grants layered on active ordinary knowledge routes. From the receiver, ki trade standing capture appends a marked, commit-pinned STI-* provenance block to an existing local Markdown file only after the source commit and path resolve and the exact grant is active. One-sided, unknown, malformed, ambiguous, or revoked declarations retain the ordinary itemized-trade fallback and grant no direct-capture authority. See the standing knowledge-intake guide for the complete workflow.
ki trade list presents visible preparations, imports, and exports across the registered repository estate. Each item identifies its peer (→ receiver or ← sender), kind (⚒ work or ⓘ knowledge), observation policy, and lifecycle: preparing or submitted, receipt state, receiver decision, and release or prune eligibility. Sender release becomes eligible according to the selected observation policy; receiver prune becomes eligible only after that release is observable. ki trade release --eligible and ki trade prune --eligible preview their batches and require --yes to apply them. These trade and the existing report and diagnostic symbols come from one bounded presentation registry; structural tree and table characters remain part of their renderers.
ki repo roadmap list includes that record context for each selected repository, so planning work and incoming or outgoing trades can be scanned together without changing either lifecycle. If the local registered trade estate cannot be read, it reports that context as unavailable and exits with status 1 after rendering the inventory.
Install a governed MCP server source from an exact annotated release, or omit the version to select its latest stable GitHub Release:
ki manage mcp install owner/repository 1.2.3
ki manage mcp install owner/repository
ki manage mcp list owner/repositoryUse explicit --auth github-cli for private repositories. KI verifies and builds the release into a versioned local installation, records path-free provenance, and atomically activates it. Updates retain complete prior versions for offline rollback; uninstall removes the source installation. Client binding remains a separate operation. See the local installation guide for authentication, update, rollback, and recovery details.
After the first immutable release, download install.sh from an exact released tag, inspect it, then run it with that tag:
curl --fail --location --proto '=https' --proto-redir '=https' --output install.sh \
https://raw.githubusercontent.com/knowledgeislands/tools-ki/vX.Y.Z/install.sh
bash ./install.sh vX.Y.ZThe installer carries the pinned public key and verifies the release's Ed25519-signed checksum manifest before downloading the platform archive. It supports macOS (Apple Silicon and Intel) and x86_64 glibc Linux. Use an explicit version for every public installation. The equivalent pinned pipe form is curl -fsSL https://knowledgeislands.info/install/ki | sh -s -- vX.Y.Z; omitting the version deliberately resolves the latest release.
The Homebrew tap will move to these same release artifacts after that first immutable release.
Install ki and run it for the first time takes this further: what ki bootstrap does, how to register the first repository, and how to verify and recover from each step.
install.sh --link is exclusively for development from a local checkout. Read the local development guide for that path and the ki dev local set <harness-id> <path> / on [harness-id] / off [harness-id] lifecycle. Each installed Harness can have an independent local source; omitting the ID from on or off applies the transition to all configured sources.
The tracked ki(1) manual defines the intended V1 command surface.
- Decision Records explain why the platform is shaped as it is.
- Specifications define the accepted observable behaviour and its verification evidence.
- Guides explain how to operate, develop, and release
ki, routed by audience: user guides and developer guides. - Roadmap shows active delivery work and its lifecycle state.
- Changelog inventories the public V1 baseline while pre-V1 tags remain the shipped
0.xrelease record.
ki manage search <query> searches only verified installed harness capabilities, without contacting a registry or discovering a repository.
ki repo store list|create|bind|unbind manages the store roles declared by a selected Knowledge Base: notes remains the repository root, while sources and legacy use explicit machine-local bindings. ki manage vscode check and sync --write consume bound sources for chezmoi-managed workspace and trusted-folder projections, ignore legacy, and never infer associations from directory names or run chezmoi apply. See the repository operations and VS Code projection guides.
ki manage diag reports machine-managed installation, configuration, registry, and path state, and ki manage doctor checks that state and reports direct-CWD legacy .ki-meta/ and .ki/ directories. ki manage repair reconciles missing, dangling, or stale configured user-skill projections, and ki repo repair does the equivalent for a selected repository's KI-managed projections; --dry-run changes nothing in either. ki manage docs prints labelled public CLI, site, manual, and roadmap locations without opening a browser.
Maintain a local installation explains the local-only behaviour and safety boundary of each of these, including which of them only ever report. Use ki --help or ki <command> --help for exact grammar; the tracked manual remains authoritative.