# Index your code The code index tells an agent where to look. Memory tells it why the code is that way. Set up both, and the next task can begin with the relevant decisions and the relevant source. ## What leaves your computer {#what} The CLI reads supported source files locally and extracts symbol names, kinds, relative file paths, line ranges and fingerprints. It sends that map to Korium, not the source text. Names and paths can still be sensitive, so inspect the output before your first upload. The index supports Elixir, Rust, Swift, Python, shell, JavaScript, TypeScript, Go, Java, Ruby and C, plus SQL, justfiles, Dockerfiles and Cedar policies. From YAML, TOML, JSON, Terraform, HCL, XML, property list and `.env` files it takes the keys, blocks and names, never the values. It is a symbol index, not a full-text copy of the repository. For Markdown, HTML, `.heex`, CSS and other files outside that set, use a local text search. [Korium:Code](code.html#misses) lists what each format contributes. ## 1. Install the Mac CLI {#install} Download the current Korium installer from your dashboard. Open the package, review the license and follow the installer. It asks for administrator authorization because it installs the command for the Mac. ``` korium-cli version korium-cli help ``` The installer puts the command at `/usr/local/bin/korium-cli`. You do not need to move the binary or create a symlink. The download shows on your dashboard only once your workspace has Code Indexer. You can add it when you pick a plan, with the Add Code Indexer box. Later, an owner or admin of the workspace that pays for the plan can turn it on under Plan and billing on the Account page, which shows the cost before you pay. If your plan does not offer Code Indexer, that section may offer View plans instead, which lists the plans you can switch to and shows each plan that offers Code Indexer both with it and without it. If you still have no download, ask your workspace administrator or [contact Kyroco](mailto:robert@kyroco.ai). This is the native macOS client. These instructions are not a Linux or Windows installation recipe. ## 2. Sign in on this Mac {#login} ``` korium-cli login korium-cli status ``` Finish the browser sign-in and return to the terminal. Status checks server reachability, the locally saved sign-in and whether the connection is accepted. The CLI keeps credentials in the macOS keychain. It has no supported option to receive a bearer token through an argument or environment variable. This sign-in is separate from the assistant’s MCP connection. If you skip this step, the first command that needs a sign-in, such as `korium-cli index`, opens the same browser sign-in and then carries on. Decline it and the command stops without sending anything. ## 3. Inspect the map before sending it {#preview} From inside your repository, run: ``` korium-cli index --dry-run ``` This extracts and reports without uploading, and does not need a sign-in. Check the reported repository root, commit and symbol count. If you are inside a nested dependency, pass `--repo-root` explicitly so there is no ambiguity about the repository you intend. ``` korium_preview_dir=$(mktemp -d) korium-cli index --dry-run --cards-out "$korium_preview_dir/cards.json" ``` The JSON file shows the cards that would be sent. Review it locally; do not post it publicly if the names or paths are private. You can limit discovery with a repeatable `--include` path, but keep the same intended scope when maintaining that index. ## 4. Upload, then verify publication {#publish} ``` korium-cli index ``` Run it from any branch. Each branch is its own index, and indexing one never replaces another. A search that names no branch reads the repository’s trunk: the branch the remote (`origin`) points at. If git has not recorded which branch the remote considers its default, the CLI does not guess and says so; Korium keeps the trunk it has, or, for a repository with none, takes the first branch it indexes. `git remote set-head origin -a` teaches git the default branch. Once a repository has a trunk, it moves to another branch only when an index of that branch finishes, sent from a checkout whose remote names it as the default, by an account allowed to publish this repository’s index. A detached checkout is turned down before anything is sent. Korium removes the index of any branch other than the trunk once nobody has indexed that branch for 14 days. `korium-cli repos` shows how long each one has left. A shallow clone is turned down too. Korium names a repository by its first commit, and a shallow clone does not hold it; run `git fetch --unshallow` first. `korium-cli status` says the same when run inside one. The CLI reports extraction, upload, embedding and publication separately. Watch the reported progress rather than relying on a fixed time estimate. The default index command makes a bounded attempt to verify publication. If searches are still not answering with the new index when that wait ends, it exits with status 1. It can still finish with exit status zero when there was no suitable symbol to prove the new publication, or when it could not tell whether symbols from removed files have stopped answering. Read the final outcome, not just the exit status.
What happenedWhat it provesWhat to do next
Upload accepted, including a run with --no-waitThe upload step finished, not that this commit answers searches.Check publication with a later index run and a known-symbol search.
Publication verifiedThe CLI observed the expected serving result for what it could check.Compare the returned commit and read the symbol in your checkout.
Still not answering when the wait ended (exit status 1), or nothing suitable to checkPublication is not proved, even if the command exited zero.Follow the CLI’s retry guidance. Do not report a green job as a searchable new index.
`--no-wait` returns after acceptance. That is useful in hooks, but the next index run and a known-symbol search still need to check what is serving. After your first index in a repository with no Korium hook, korium-cli asks once whether to keep that repository’s index current automatically. Yes installs the [Git hook](git-and-github.html#local); no is remembered, and `korium-cli hooks install` still works later. It asks only when you run it in a terminal. ## 5. Search, then verify the source {#search} ``` korium-cli search "RefundPolicy calculateRefund" ``` Phrase the query toward the symbol or concept you expect to exist. The search reads the index of the branch your checkout is on, or the trunk when Korium holds no index for that branch, and says which. Add `--branch NAME` to search one branch and no other. Read the branch and commit named at the beginning of the answer, then open the returned file and line range locally. A location from another commit needs verification. If the repository has no trunk, for example because its trunk index was deleted or its default branch has not been indexed yet, the search lists the branches Korium holds for it and how to search one. Through MCP, the corresponding tool is `code_locate`. Pass the actual checkout SHA from `git rev-parse HEAD` and the canonical repository identity printed by the CLI, such as `rootsha:…`. A display name may resolve to a different repository record. Pass `branch` to search that branch’s index; leave it out and the trunk answers. When `code_locate` finds that a checkout’s index is missing or behind, its answer says what to do: run `korium-cli index` in the checkout, which indexes the branch the checkout is on. Korium also says this in the instructions it sends an assistant when it connects, so an agent can bring the index up to date itself. An empty result may mean an unknown repository, an unindexed commit, an unsupported file type or simply a weak query. Those are different cases; read the returned reason before reindexing everything. ## 6. Keep it current {#maintain} The CLI first compares its repository manifest with the server’s record. A match avoids another upload; a difference lets it prepare the update against what the server holds. Commit before indexing when you want the index to match a commit exactly, since a commit label does not certify uncommitted file contents. Run `--dry-run` after a large reorganization. Use `--allow-removals` when the intended update removes symbols; it permits shrinking the index, not deleting source files. Use `--full` only when your installed release supports it and you deliberately need a complete snapshot. To keep indexes current without typing, add the [Git hook](git-and-github.html#local) and an agent hook for [Claude Code](claude-code.html#hooks) or [Codex](codex.html#hooks). Each updates the index of the branch it runs on. `korium-cli repos` lists every index in your workspace. `korium-cli delete BRANCH` deletes one branch’s index and leaves your git branch alone. Deleting the trunk, or the repository’s last index, needs `--allow-removals`. Use the [setup checklist](release-status.html) to verify transcript sources, memory connections and your branch code indexes before automating the work.