# Use Korium CLI from Bash

The CLI signs this Mac in, builds a code map and searches that map. It is not the memory capture interface. Use MCP for agent_search and agent_capture.

## The commands you will actually use {#commands}

<div class="table-scroll"><table><thead><tr><th>Command</th><th>Purpose</th></tr></thead><tbody><tr><td><code>version</code> / <code>help</code></td><td>Check the installed release and supported options.</td></tr><tr><td><code>login</code> / <code>status</code></td><td>Authorize this Mac and check the connection. You don’t have to log in first: a command that needs a sign-in starts one.</td></tr><tr><td><code>index</code></td><td>Build and upload the symbol map of the branch the checkout is on.</td></tr><tr><td><code>search "query"</code></td><td>Find symbols in this repository, on the branch the checkout is on, or on the trunk when Korium holds no index for that branch. Add <code>--branch NAME</code> to search one branch and no other.</td></tr><tr><td><code>delete BRANCH</code></td><td>Delete Korium’s index of one branch of this repository. Your git branch is not touched. Deleting the trunk, or the last index Korium holds for the repository, needs <code>--allow-removals</code>. In a workspace where only some accounts may publish an index, only they may delete one.</td></tr><tr><td><code>repos</code></td><td>List the code indexes in your workspace, one row per branch, from any folder: which one is the trunk, who indexed it and when, at which commit and reading version, when a search last used it, and how long until Korium removes a branch nobody indexes any more. Add <code>--json</code> for every field as Korium sends it, or <code>--help</code> for what each column means.</td></tr><tr><td><code>hooks install</code></td><td>Add the supported post-commit hook, and print an end-of-task hook for Claude Code. Add <code>--branch-deletes</code> to also add a reference-transaction hook, so deleting a local branch deletes that branch’s index. Renaming a branch does not.</td></tr><tr><td><code>hooks uninstall</code></td><td>Remove every hook Korium installed, never somebody else’s. Add <code>--branch-deletes</code> to remove only the branch-delete hook.</td></tr><tr><td><code>logout</code></td><td>Remove this Mac’s saved CLI sign-in.</td></tr><tr><td><code>licenses</code></td><td>Read the bundled open-source licenses.</td></tr></tbody></table></div>

There is no `korium-cli capture` or `korium-cli agent_search` command. A shell script that needs to save company memory needs an authenticated MCP client, not a made-up CLI subcommand.

## Signing in when a command needs it {#sign-in}

`index`, `search`, `delete` and `repos` need this Mac to be signed in. When it is not, or when Korium no longer accepts the saved sign-in, the command runs the same browser sign-in as `korium-cli login` and then carries on with what you asked. An agent running one of these commands is treated like a person: the page opens and the command waits for it.

If you decline, or the sign-in is not finished within three minutes, the command stops with exit status 1. The index is not updated, and for `delete` nothing was deleted. With `--json`, the sign-in messages go to standard error, so standard output stays JSON. `index --dry-run` never needs a sign-in.

A hook never waits. Korium’s Git hooks and the end-of-task hook that `hooks install` prints pass `--from-hook`. On a Mac that is not signed in, the hook returns at once without indexing, and `index` exits with status 3. A sign-in also opens in your browser in the background, and the index runs once you finish, unless a sign-in is already open, you turned one down in the last hour, or there is no screen to show it on. See [Git hooks](git-and-github.html#local).

## A small indexing script {#script}

Pass the repository path explicitly. This script checks the prerequisites, confirms the connection and starts the CLI’s bounded publication check. It does not install anything. `status` runs first, so on a Mac that is not signed in the script stops there instead of opening a sign-in in the browser.

```
#!/bin/bash
set -euo pipefail

korium_repo=${1:?"Usage: index-project.sh /path/to/repository"}
command -v korium-cli >/dev/null
git -C "$korium_repo" rev-parse --show-toplevel >/dev/null

korium-cli status
korium-cli index --repo-root "$korium_repo"
```

Run it with `bash index-project.sh "/path/to/repository"`, replacing the path. A nonzero exit stops the script, but exit zero does not certify searchable publication. Inspect the final result and verify a known symbol at the expected commit before reporting the index ready.

The default index command makes a bounded attempt to verify publication. It can finish with exit status zero while searches still answer from an older index, or while there was no suitable symbol to prove the new publication. Read the final outcome, not just the exit status.

<div class="table-scroll"><table><thead><tr><th>What happened</th><th>What it proves</th><th>What to do next</th></tr></thead><tbody><tr><td>Upload accepted, including a run with <code>--no-wait</code></td><td>The upload step finished, not that this commit answers searches.</td><td>Check publication with a later index run and a known-symbol search.</td></tr><tr><td>Publication verified</td><td>The CLI observed the expected serving result for what it could check.</td><td>Compare the returned commit and read the symbol in your checkout.</td></tr><tr><td>Still pending, or nothing suitable to check</td><td>Publication is not proved, even if the command exited zero.</td><td>Follow the CLI’s retry guidance. Do not report a green job as a searchable new index.</td></tr></tbody></table></div>

## Choose flags deliberately {#flags}

<div class="table-scroll"><table><thead><tr><th>Option</th><th>When to use it</th></tr></thead><tbody><tr><td><code>--repo-root PATH</code></td><td>Select the intended repository from another working directory.</td></tr><tr><td><code>--include PATH</code></td><td>Limit the folders read. Repeat for multiple paths.</td></tr><tr><td><code>--dry-run</code></td><td>Extract and report locally. No upload or sign-in required.</td></tr><tr><td><code>--cards-out PATH</code></td><td>Write the extracted cards to a local JSON file for inspection.</td></tr><tr><td><code>--rehearse</code></td><td>Ask the server whether it would accept the declaration. Sends no cards and creates no import ledger.</td></tr><tr><td><code>--no-wait</code></td><td>Return after acceptance rather than waiting for searchable publication.</td></tr><tr><td><code>--allow-removals</code></td><td>Permit an intended update to remove symbols from the index.</td></tr><tr><td><code>--full</code></td><td>Send a full snapshot instead of relying on an incremental plan.</td></tr><tr><td><code>--replace</code></td><td>The same as <code>--full</code>: both send every file.</td></tr><tr><td><code>--branch NAME</code></td><td>Must match the branch the checkout is on; korium-cli refuses a name that disagrees. It never picks which branch is indexed.</td></tr><tr><td><code>--from-hook</code></td><td>Set by Korium’s hooks. On a Mac that is not signed in, the command returns at once with exit status 3 and never waits for a sign-in.</td></tr><tr><td><code>--debug</code></td><td>Trace tool names, timing, status and request IDs. Review the output before sharing it.</td></tr></tbody></table></div>

`--retrack` is gone. korium-cli refuses it and sends nothing: each branch is its own index, so there is no index to move to another branch. Run `korium-cli index` from the branch you want indexed.

Each branch has its own index, so a publisher on one branch never replaces another branch’s index. `--replace` rebuilds only the index of the branch the checkout is on. To change which branch a search reads when it names no branch, change the remote’s default branch, run `git remote set-head origin -a`, then index that branch. When git has not recorded the remote’s default branch, the CLI does not guess and tells Korium nothing about the trunk: Korium keeps the trunk it has, or, for a repository with none, takes the first branch it indexes.

Index output and search output are intended for people. Don’t build a fragile parser around spacing or a sample progress sentence. Use the structured MCP response when an integration needs structured code-search results.

## Handle failures without hiding them {#exit}

Check the command’s exit status, then read its final publication result. A nonzero exit means the command failed or was refused; a zero exit still does not prove the new index is searchable. If you pipe output through `tee`, keep `set -o pipefail` so logging does not hide a failure.

The CLI can return exit code 2 for a refusal. Some agent Stop hooks interpret that as “continue the task.” A shell command’s exit meaning and a hook’s exit meaning are not interchangeable. The Claude Code Stop hook that `hooks install` prints ends in `|| exit 1` for that reason.

The Codex <a href="examples/korium-task-end.sh" download>task-end example</a> emits non-blocking JSON notices for skipped or failed uploads, and for a completed command whose publication remains unverified. It emits `{}` when skipping a repeated Stop continuation.

## Run on a prepared Mac, not with a copied token {#unattended}

Set up the CLI interactively under the same operating-system user that will run the script. Confirm `status` and a real index work in that execution context. A working terminal session does not prove a background service has the same keychain access.

Do not copy keychain files into CI, add a token flag or assume a temporary GitHub-hosted runner has your Mac’s sign-in. Use the [self-hosted runner guide](git-and-github.html#github) only after the host, user and repository permissions are deliberately configured.

## If the script needs company memory {#memory}

Use an MCP client that supports the Korium OAuth flow, holds its own refresh state and requests the scopes it needs. The endpoint is `https://api.kyroco.ai/mcp`. Read [MCP and OAuth](connect-any-mcp-client.html) before implementing a client.

A bare `curl` command with a token copied from an assistant is not a supported unattended setup. Do not put credentials into shell history or workflow logs to make a demonstration work.