CLI
keryx is a thin client of the same HTTP + SSE API that Slack, the MCP
server and the web surfaces use. Anything the CLI can do, the API can do.
Commands
| Command | Does |
|---|---|
keryx auth login | Device-code flow; the token lands in the OS keychain, never a dotfile |
keryx investigate | Start an investigation from an alert payload or a free-text query |
keryx investigations | List investigations, newest first |
keryx trace <id> | Render the full evidence-cited trace |
keryx trace <id> --follow | Stream trace steps live over SSE |
keryx resolve <id> | Close an investigation with a resolution |
keryx feedback <id> | 👍/👎 on a finding; feeds retrieval scoring |
keryx doctor | Diagnose the install — API, migrations, MCP servers, RBAC, provider key |
keryx support-bundle | Export redacted logs, config and versions for an issue report |
keryx mcp | Run the MCP server over stdio |
Output
Every command that prints a result takes --json. The human format is for
reading; the JSON format is the contract, and it is the same shape the REST
API returns.
Exit codes are meaningful: 0 success, 1 a real failure, 2 a usage
error. A command that could not reach the API exits non-zero rather than
printing an empty list.
Authentication
The CLI holds an API key in the OS keychain and sends it as
Authorization: Bearer. Keys are class-separated — a worker key is
refused on public routes rather than silently accepted — hashed at rest with
argon2id, and revocable.
The CLI authenticates against core-api's own API-key table, not against the web app's Better Auth instance. Two identity systems, deliberately: one authenticates a program, the other authenticates a person at a keyboard.