@parsemend/cli

The Parsemend CLI runner (§4.8 of the platform design spec): pulls a fix context bundle for an issue from your Parsemend instance and runs the same root-cause → solution → coding pipeline locally, against your own working copy, using your own model keys (or a local claude CLI handoff). Source code is never uploaded to Parsemend's servers — only the opt-in post-back sends root-cause/diff data back, never files.

Install

npm install -g @parsemend/cli
# or, from this repo:
npm install && npm run build && npm link

Requires Node 20+.

Usage

parsemend login                # sign in via your browser
parsemend issues               # list what you can fix
parsemend fix <issue>          # run the pipeline
parsemend mcp                  # serve an agent session (see below)
parsemend post-back <issue-id> # publish a prior local run's results
parsemend logout
parsemend upgrade              # update to the latest published version
parsemend --version

Naming an issue

parsemend issues lists what you can fix, most recently seen first:

$ parsemend issues
postlyra-12  error    3m ago  Undefined property $slug
stayblox-84  warning  2d ago  Timeout talking to the channel manager

2 issues. Run `parsemend fix postlyra-12` to start on one.

The first column is the id every other command takes. fix also accepts the numeric database id and a full issue URL, but <project-slug>-<number> is the form worth remembering — it is the one you can read off a stack trace conversation and type from memory.

Narrow the list with --project <slug>, --status <status> (or --status all; the default is unresolved), and --limit <n>. --json emits the raw rows for scripting.

Fixing from a Claude Code or Codex session

parsemend fix drives a model itself, which means it needs a provider API key and runs the coding step as a one-shot subprocess that cannot ask you anything. If you already work in an agent session, turn it around: let the session drive and let Parsemend supply the context.

Register the server once:

claude mcp add parsemend -- parsemend mcp     # Claude Code
codex mcp add parsemend -- parsemend mcp      # Codex

Then, in a session, pick your model and say what you want:

/model opus-5
> fix postlyra-12

The session calls get_issue_context for the stack trace, breadcrumbs, trace tree, related logs, and this repo's code mappings; reads and edits the code with its own tools; and calls post_back if you ask it to publish.

Four tools are exposed:

| Tool | What it does | | --- | --- | | list_issues | The same list as parsemend issues. | | get_issue_context | The whole debugging bundle, or named sections of it. Makes no model call. | | analyze_issue | Optional — runs Parsemend's own root-cause explorer and planner. This one does spend your provider key. | | post_back | Publishes what you changed, read back from git diff. Opt-in, and the only tool that sends anything out. |

No provider API key is needed for this path: the session's own model does the work, so /model is what picks it.

Signing in

parsemend login prints a short code and opens Parsemend in your browser (if it can — the URL is always printed, so an SSH session or a container works too). Sign in however you normally do, check the code on the page matches the one in your terminal, and confirm; the CLI picks up its token and tells you who you're signed in as.

No password is ever typed into the terminal. The token the browser hands back is scoped to you and labelled with the machine you signed in from, so one machine's access can be withdrawn without disturbing the others. parsemend logout removes it from this machine.

For CI, where nobody is around to approve a browser sign-in:

parsemend login --token <token>

qa commands (CI-facing)

parsemend qa run and parsemend qa export are the qa-C CI/PR-gating surface: they authenticate with a durable org token (PARSEMEND_ORG_TOKEN env var, checked first, else --token) rather than the personal login token, since CI doesn't run an interactive login.

parsemend qa run --suite <name> --org <slug> --project <slug> [--base-url <url>] [--environment <name>] [--wait] [--json]
parsemend qa export --org <slug> --project <slug> [--out <file>]

qa run triggers a suite run; with --wait it polls until the run reaches a terminal status (passed/failed/errored) and exits 0 iff passed — raw pass/fail only, never gated by per-flow triage verdicts. --sha, --branch, --pr-number, and --repository pass GitHub context through for the server's check-run/Issue-link reporting. qa export lists a project's flow definitions as YAML.

See docs/ci-example.md for a full GitHub Actions example that blocks a job on qa run --wait's exit code.

Security note

parsemend login writes ~/.parsemend/config.json, containing your personal API token in plaintext and, if you configure them, your own provider API keys. The file is written 0600 (and its directory 0700), which restricts it on POSIX systems (macOS/Linux). This offers no protection on Windows — that platform is out of scope for this version.

Configuration

The CLI ships knowing where Parsemend lives — https://api.parsemend.com — so nothing ever asks you for a URL. Set PARSEMEND_API_URL to point at a self-hosted or staging deployment; the environment variable wins over the saved config.

Model roles (explore/conclude/format/code) resolve from, in order: a CLI flag, a PARSEMEND_MODEL_<ROLE> environment variable (e.g. PARSEMEND_MODEL_EXPLORE=anthropic:claude-haiku-4-5), or a built-in default. Supported providers: anthropic, openai, google, ollama (served via an OpenAI-compatible local endpoint).

--executor claude_code hands the coding step to your local claude binary instead of the built-in tool loop, and --model-code selects the model it runs:

parsemend fix postlyra-12 --executor claude_code --model-code anthropic:claude-opus-5

The anthropic: prefix is dropped on the way through (Claude Code takes claude-opus-5 or opus); naming another provider is an error rather than a silent fallback. Left unset, Claude Code keeps whatever model you configured for it.

Tests

npm test

License

MIT — see LICENSE.