CLI Reference
The nitpin command wires repos to projects, launches agents, and syncs stores. It’s
also the MCP server your coding agent talks to (started automatically — you never run
that part yourself).
nitpin <command> [options]
nitpin --help # list commands
nitpin --version
Commands act on the project resolved from your current directory: the repo’s
.nitpin/ store, or its nitpin.yaml link, or — outside any repo — the app’s active
project. Many commands accept --project PATH to target another project explicitly.
Setup
nitpin init [name] [--path PATH] [-y]
Set up nitpin in this project — creates the issue store and wires up your coding agent.
| Option | Meaning |
|---|---|
name | Project name (default: the current folder’s name). |
--path PATH | Store the project at this path instead of ./.nitpin, leaving a nitpin.yaml pointer in the repo. |
-y, --yes | Update the agent wiring (MCP config + skill) to the shipped version without asking, even if edited. |
Creates ./.nitpin/ (the store), .mcp.json, and the agent skill. Safe to re-run:
an existing store is never touched; drifted wiring prompts before updating (or
updates silently with -y). Restart your coding agent afterwards so it picks up the
MCP server.
nitpin install [harness] [--quiet] [--force]
Install nitpin into your coding agents, user-globally (alias: nitpin setup).
| Option | Meaning |
|---|---|
harness | Set up just one agent: claude, codex, opencode, or pi. |
--quiet | Set up every detected agent without prompting. |
--force | Reinstall even where nitpin is already set up. |
With no arguments, an interactive wizard shows every detected agent — check to install, uncheck to remove. Re-runs skip agents that are already current.
nitpin uninstall [harness] [--quiet]
Remove nitpin from one coding agent, or from all of them with --quiet.
Projects
nitpin open [path]
Open the project for path (default: the current directory) in the nitpin app and
make it the active project.
nitpin projects
List the projects nitpin knows about, with their paths.
nitpin link [target]
Use an existing nitpin project for this repo. target is a project name or path;
omit it to pick from a list. Writes the repo’s nitpin.yaml pointer.
nitpin unlink
Stop using the linked project in this repo (removes the pointer). A store living inside the repo can’t be unlinked — it travels with the repo.
nitpin clone <url> [dest]
Clone a git repo and open its nitpin project in one step. If the repo already carries
a .nitpin/ store you join it; if not, one is created. dest defaults to a nitpin-
managed clones folder.
nitpin set <key>=<value>
Set a project setting from the terminal (the same knobs as Project Settings):
| Key | Values | Meaning |
|---|---|---|
worktrees | true / false | parallel agents in isolated worktrees, or one at a time on the main checkout |
landing | main / branch | where code fixes land |
defaultInvolvement | asyncAsk / asyncAuto | park questions as comments, or decide unattended |
autotriage | integer (negative = off) | suggest a re-triage when unclustered issues outgrow clustered ones by this ratio |
resolvedIssueLimit | positive integer (empty to reset) | how many resolved issues the Backlog shows before archiving |
The backlog
nitpin status
This project’s dashboard: issue counts by state, sub-issues still open, the triage picture (with a re-triage recommendation when warranted), and which coding agents are available.
nitpin list [--state STATE]
List the project’s issues — number, state, title, and sub-issue counts. --state
filters to one of unresolved, in_progress, resolved, wont_fix, split.
nitpin clusters
Print the current triage clusters — labels, summaries, members — and your overrides.
Agents
nitpin triage [--run] [--harness ID] [--only N,N,…] [--project PATH]
Group the open issues into clusters, running your coding agent headlessly.
| Option | Meaning |
|---|---|
--run | Actually run it (without --run, prints what triage is and how to start it). |
--harness ID | Use a specific agent (claude, codex, opencode, pi). |
--only N,N,… | Re-triage only these issues, merging into the existing clusters instead of replacing them. |
nitpin fix [ISSUE] [options]
Fix sub-issues with a coding agent: one issue, a cluster, a batch, or the whole backlog. Exactly one scope is required:
| Scope | Meaning |
|---|---|
ISSUE | fix just this issue |
--cluster ID | fix one triage cluster |
--sweep N,N,… | fix a set of small unrelated issues in one batched session |
--all | fix the whole open backlog (triaging first if needed), one agent per cluster |
| Option | Meaning |
|---|---|
--involvement ask|auto | on ambiguity: park questions as comments (ask, default) or decide unattended (auto) |
--agent ID | use a specific agent instead of the size-based routing |
--model M | force a model (e.g. opus, gpt-5) |
--effort E | force a reasoning-effort level (e.g. low, high) |
--max K | with --all: max agents at once |
--project PATH | fix another project |
Each unit routes through your task models by its triage
size; --agent/--model/--effort pin the routing instead.
nitpin revert --issue N --sub-issue M [options]
Revert one landed fix and reopen its sub-issue, keeping every later fix. See
Reverting a Fix. --agent / --model / --effort pick
who does the reverting; --sub-issue 0 is the issue’s body.
Sync & maintenance
nitpin sync [--push|--pull] [--project PATH]
Sync the project’s issue store with its git remote — commit, pull, and push (or just one direction). See Sync Issues with Git.
nitpin update
Update a standalone (curl-installed) nitpin CLI to the latest version. A CLI that
shipped inside the app defers to the app’s updater.
nitpin migrate <path> [--check] [--json]
Bring an older project store up to this nitpin’s format. --check reports what would
happen without changing anything; migrations back the store up first. You’ll rarely
need this — stores from recent versions read in place.
Environment variables
| Variable | Effect |
|---|---|
NITPIN_HOME | Override where nitpin keeps its user-wide data (default ~/.nitpin). |
NITPIN_PROJECT | Pin every command to a specific project store, overriding directory-based resolution. |
Plumbing
Two commands exist for machinery rather than people: nitpin mcp runs the MCP server
(your coding agent starts it automatically), and nitpin release <issue> force-drops
every claim on an issue — the terminal escape hatch when an agent died mid-work (the
Cockpit’s Stop button does the same thing with a click).