@cruxy/cli

An agentic coding CLI that plans, edits, tests, and ships from your terminal — powered by the Cruxy API.

Cruxy is a terminal-first coding agent that works directly in your repository — reading code, editing files, running commands, and verifying its own work, with an approval gate before anything touches disk.

Install

npm install -g @cruxy/cli

cruxy run "explain this codebase"   # first run guides you through setup

On your first interactive run with no key, cruxy walks you through getting one, validates it, and saves it to ~/.cruxy (owner-only) — no env var needed. You can also run setup on demand:

cruxy login                         # set or replace your API key
cruxy init                          # key + a project CRUXY.md + a first run
export CRUXY_API_KEY=cxy_live_...   # …or just use an env var (always wins)

Features

• Onboarding — a guided first run (cruxy login / cruxy init on demand): get a key, validate it live, and save it to ~/.cruxy/credentials.json (0600) — never to config.json, the project, or env files. Keys resolve env → credentials store. Non-interactive runs stay fail-loud (CRUXY_E_AUTH_MISSING_KEY), never blocking on input.
• Tools — read_file, write_file, edit_file, glob, list_files, grep_files, run_command, git_status, apply_patch, search_codebase, list_skills, load_skill, create_pull_request.
• Pull requests — cruxy pr (and the create_pull_request tool) turn the current changes into a PR: feature branch → conventional commit → push → open the PR, with a generated title/body, all behind the approval gate. GitHub ships first behind a swappable ForgeProvider; the token is read from GITHUB_TOKEN / GH_TOKEN / gh auth token (never stored). It never commits or pushes on a protected branch, never force-pushes, and never bypasses the commit/push hooks.
• Codebase index — a local, incremental semantic index (cruxy index) behind the search_codebase tool. Embeddings run on-device via fastembed (ONNX, bge-small-en-v1.5) with no network calls; the store is SQLite at .cruxy/index.db. Only changed files are re-embedded; .gitignore / .cruxyignore are respected and secrets (.env*, keys) are never indexed.
• Skills — reusable, task-specific instructions in a SKILL.md (frontmatter + markdown), discovered via list_skills and pulled on demand with load_skill (progressive disclosure: only name + description are in context until a skill is loaded). Layered project > user > builtin, strictly validated, and never auto-executed.
• Agent — streaming output, multi-turn interactive sessions, context compaction, and awareness of git state and project instructions (CRUXY.md).
• Streaming render — flicker-free live output: a single in-place status line (spinner while the model thinks / tools run), append-only committed text, syntax-highlighted code fences, tool-call notes, and diffs drawn by the same renderer as the approval prompt. Degrades cleanly: piped/CI output is plain append-only text with zero ANSI (chrome on stderr), NO_COLOR drops color, and CRUXY_NO_SPINNER=1 stills the animation.
• Plan mode (opt-in: cruxy run --plan, /plan, or agent.planMode) — the agent proposes a structured, step-by-step plan; you approve it once, then it executes with live per-step status. Approving consents to the shape of the work — every action still passes the approval gate, and destructive/ungrantable actions always re-confirm even after approval.
• Safety — a single approval gate with diff previews that fails closed; read-only tools never prompt; file access is confined to the project root; shell commands run bounded.

Interactive slash commands: /help, /clear, /compact, /reload, /exit.

For unattended runs, pass --yes to approve every action.

Codebase search

cruxy index            # build / refresh the local index (.cruxy/index.db)
cruxy index --status   # show what's indexed
cruxy index --force    # re-embed every file

The index refreshes itself lazily the first time the agent calls search_codebase, so it works even without running cruxy index first. The bge-small embedding model (~130 MB) downloads and caches on first use.

Skills

cruxy skills            # list the resolved skill catalog
cruxy skills --status   # show source directories and validation errors

Add a skill by creating <name>/SKILL.md under .cruxy/skills/ (project) or ~/.cruxy/skills/ (user); shipped builtins are the lowest layer. See the built-in using-skills skill for the authoring rules.

Pull requests

export GITHUB_TOKEN=ghp_...   # or GH_TOKEN, or be logged in with `gh`

cruxy pr                              # generate + open a PR for the current changes
cruxy pr --base develop               # target a specific base branch
cruxy pr --title "fix(cli): …"        # override the generated title
cruxy pr --draft                      # open as a draft

The whole plan — branch, commit, and PR title/body — is shown for approval before anything runs. On a protected branch (main/master/configured via git.protectedBranches) cruxy branches off first; the base defaults to git.defaultBase, then the repo's default branch, then main.

Checkpoints & rollback

Before an agent run's first file mutation, cruxy snapshots the working tree (tracked + untracked non-ignored files; gitignored paths and the secrets denylist are never captured). cruxy rollback undoes the whole run — creates, edits, deletes — in one operation:

cruxy checkpoint list        # saved checkpoints, newest first
cruxy rollback               # restore the most recent checkpoint
cruxy rollback <id>          # restore a specific one

Rollback is destructive, so it previews exactly what will change (including anything that changed outside the run — surfaced, never silently clobbered) and always asks for approval; it cannot be session-granted and refuses to run non-interactively (CRUXY_E_ROLLBACK_APPROVAL_REQUIRED).

In a git repo, snapshots go into the git object database via a temporary index — HEAD, your index, the stash, and every ref are untouched, and nothing shows up in git status. Outside a repo, a content-addressed shadow copy under .cruxy/checkpoints/ is used. Retention is bounded (checkpoint.retention, default 10; disable with checkpoint.enabled = false).

Boundary: checkpoints cover working-tree files only. Commits, pushes, and PRs made during a run are never undone — the rollback preview says so.

Errors & exit codes

Every user-facing error prints a title, the cause (when known), concrete next steps, and a stable code (e.g. CRUXY_E_GATEWAY_UNREACHABLE). Pass --verbose (or --log-level debug / DEBUG=1) to see the underlying error and stack; NO_COLOR disables color. Exit codes are stable per category, so scripts can branch on them:

| Exit | Category | Example codes | | ---- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 | success | — | | 1 | internal | CRUXY_E_INTERNAL | | 2 | usage | CRUXY_E_USAGE, CRUXY_E_CONFIG_KEY_UNKNOWN, CRUXY_E_PROVIDER_UNSUPPORTED, CRUXY_E_GIT_PROTECTED_BRANCH, CRUXY_E_PLAN_INVALID, CRUXY_E_PLAN_REVISION_LIMIT, CRUXY_E_CHECKPOINT_NOT_FOUND | | 3 | config | CRUXY_E_CONFIG_PARSE, CRUXY_E_CONFIG_INVALID | | 4 | auth | CRUXY_E_AUTH_MISSING_KEY, CRUXY_E_AUTH_INVALID, CRUXY_E_FORGE_AUTH | | 5 | network | CRUXY_E_GATEWAY_UNREACHABLE, CRUXY_E_GIT_PUSH_FAILED | | 6 | api | CRUXY_E_API, CRUXY_E_API_RATE_LIMIT, CRUXY_E_API_OVERLOADED, CRUXY_E_BUDGET_EXHAUSTED, CRUXY_E_FORGE_API | | 7 | filesystem | CRUXY_E_FILE_NOT_FOUND, CRUXY_E_PERMISSION_DENIED, CRUXY_E_PATH_ESCAPE, CRUXY_E_CHECKPOINT_FAILED | | 8 | index | CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE, CRUXY_E_INDEX_STORE_UNAVAILABLE, CRUXY_E_INDEX_FAILED | | 9 | skill | CRUXY_E_SKILL_INVALID, CRUXY_E_SKILL_NOT_FOUND | | 10 | approval | CRUXY_E_APPROVAL_REQUIRED, CRUXY_E_PLAN_APPROVAL_REQUIRED, CRUXY_E_ROLLBACK_APPROVAL_REQUIRED |

The LLM client is @cruxy/sdk — provider-agnostic, built over fetch, with no vendor SDKs.

License

MIT