Use Korium CLI from Bash

The commands you will actually use

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

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.

A small indexing 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.

Choose flags deliberately

--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

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 task-end example 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

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 only after the host, user and repository permissions are deliberately configured.

If the script needs company 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 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.