@rayul/kordis

The CLI binary is kordis — only the npm package name is scoped.

Public registry CLI for agentic-coding packages — skills, project rules, MCP servers, hooks, custom agents.

Quick start

npx @rayul/kordis@latest setup           # one-time: register kordis with Claude Code / Codex / Gemini CLI
npx @rayul/kordis@latest search sql      # find a skill
npx @rayul/kordis@latest read rayul/sql-reviewer   # JIT-load into your agent context

Or install globally:

npm install -g @rayul/kordis
kordis setup

kordis setup injects a guide block into your agent tools' global instruction files (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md) so the agent recognises kordis automatically in future sessions. The injection is idempotent — safe to re-run.

Restart your agent session after the first install. Long-lived sessions (Claude Code, Codex, Gemini) read those instruction files at session start, so the newly injected guide only takes effect from the next session onward.

Troubleshooting

npm install fails with EACCES … Your cache folder contains root-owned files? That's a leftover from a past sudo npm install on the same machine — not specific to kordis. Fix once with:

sudo chown -R "$(id -u):$(id -g)" ~/.npm

Then re-run the install — no sudo needed.

Commands

| command | purpose | |---|---| | kordis search <query> | search the registry | | kordis info <slug> | inspect a package | | kordis read <slug> | JIT-fetch body into agent context (skill / project-rules / custom-agent only) | | kordis pull <slug> | install into the current project (mcp-server / hook) | | kordis push <file> | publish a new package or version | | kordis login / logout / whoami | identity | | kordis setup | inject usage guide into Claude Code / Codex / Gemini CLI globals |

Pass --json on any command to get machine-readable output.

Configuration

| env var | purpose | default | |---|---|---| | KORDIS_API_URL | registry endpoint | https://api.kordis.dev | | KORDIS_HOME | config + token fallback dir | ~/.kordis |

Refresh and access tokens are stored in the OS keychain via keytar (with a file-based fallback at ~/.kordis/.tokens.json, mode 0600, when keytar is unavailable).

Privacy & environment variables

Kordis collects two opt-in signals, both off by default. Both can be set non-interactively for agents (kordis setup --personalization on|off and kordis setup --error-telemetry on|off) and both have an env-var escape hatch that overrides config.

| env var | purpose | default | |---|---|---| | KORDIS_NO_CONTEXT=1 | suppress personalization header even if opted in | off | | KORDIS_NO_TELEMETRY=1 | suppress error telemetry POST even if opted in | off | | KORDIS_NO_KEYCHAIN=1 | force plaintext token storage even when keytar loads (escape hatch for macOS keychain-prompt fatigue) | off | | KORDIS_DEBUG=1 | surface auto-finalize stage outcomes to stderr (diagnostic) | off |

What error telemetry carries (0.7.0+, when error_telemetry: 'on'):

• error kind (4 enum values — auto-finalize Stage 1/2 failure, network unreachable, unhandled error)
• cli_version, node_version, platform
• message_excerpt — first 200 chars of err.message AFTER client-side sanitization (homedir → ~; unix paths ≥2 segments → <path>; Windows paths → <path>; query strings → ?<query>; JWTs → <jwt>; UUIDs → <uuid>; hex runs ≥32 → <hex>)
• optional error_code (when present on the Error) + elapsed_ms + ISO timestamp

What it NEVER carries: argv, env-var values, file paths (after sanitization), identity (user_id, username, session_id, refresh tokens), X-Kordis-Context content, full stack traces. The server route additionally ignores any Authorization header so identity can't leak in even by accident.

Docs

The agent guide that setup injects is also shipped as assets/KORDIS.md in this package.

License

MIT