Command line reference

gitring is the command line for people: review intents, approve plans and merges, settle conflicts, watch a project, and connect agents. Agents themselves use MCP (see The MCP tools).

Install it from npm with npm install -g @gitring/cli (Node 22 or later; no sign-in) and start with Review your first intent. If you installed it as @mindalike/gitring before, run npm uninstall -g @mindalike/gitring first: both install the command gitring.

Commands

Sign in

Read

Decide

Work

Workspace

Lines and tags

Connect agents

Options for every command

Environment

Naming an intent

Commands that take <intent> accept storefront#41 (project and number), #41 or 41 with --project storefront (or when only one of your projects has a #41), or the intent id int_….

Output

Results go to stdout, as plain text. Questions, progress and errors go to stderr, so gitring … > file captures only the result. With --json, stdout carries one JSON document (or one event per line for watch) in the shapes of @gitring/protocol, and an error is one JSON object on stderr: { "error": { "code", "message", "exitCode" } }.

No token appears in any output or error, with one exception: gitring tokens create prints the new agent token once, because that is its job.

Exit codes

gitring login

Sign in on this computer: approve a code in the web app, and the command line gets a person token.

gitring login [options]

gitring login shows a code and a link. Open the link in a browser where you are signed in to gitring, type the code, check that the page names this machine, and approve it. Person tokens come only from this sign-in. The command line then receives a person token: it acts as you and may approve, for 30 days. Revoke it any time in the web app (Settings, then Tokens).

For scripts, --with-token reads a person token from standard input instead, without showing it as you type. The command line never takes a token as an argument, where it would stay in your shell history.

The token is checked with the server, then stored in your config folder (credentials.json). Linux: $XDG_CONFIG_HOME/gitring or ~/.config/gitring, and macOS: ~/Library/Application Support/gitring, readable only by you (mode 0600). Windows: %APPDATA%\gitring, in your profile, readable by you and the computer's administrators. GITRING_CONFIG_DIR overrides it.

Do not sign in on a computer where an agent works with a shell as you: it can read that file, and the token can approve. Connecting an agent needs no sign-in: gitring connect asks for its own approval and keeps no token that can approve.

# Shows a code; approve it in the browser.
gitring login --server https://gitring.example.com
# Read a token from a file instead.
gitring login --server https://gitring.example.com --with-token < token.txt

With --json: { server, person, credentialsFile }.

gitring logout

Forget the token stored for a server on this computer.

gitring logout

The token itself keeps working until you revoke it in the web app (Settings, then Tokens).

# Sign out of the server you used last.
gitring logout

With --json: { server, signedOut }.

gitring whoami

Show who you are signed in as, on which server, and where the token comes from.

gitring whoami

gitring whoami

With --json: { server, person, tokenSource: "env" | "file", projects: [slug] }.

gitring projects

List your projects, with their live intents and what waits for you.

gitring projects

gitring projects

With --json: Project[] (protocol api.ts).

gitring intents

List the live intents of a project.

gitring intents <project> [options]

gitring intents storefront
# Every intent, as JSON.
gitring intents storefront --all --json

With --json: IntentSummary[] (protocol api.ts).

gitring show

Show an intent the way its page does: goal and plan, drift, conflicts settled, checks and claims, decisions, then the changes.

gitring show <intent> [options]

The diff stays folded: it is evidence for the plan. Add --diff to show it.

From a server that computes them, the header adds the base status (whether the work still applies to the newest main), Conflicts settled adds code conflicts and signature notices, and Checks and claims adds the five claims gitring checks on every push, in the words of the intent page.

gitring show storefront#41
# Unfold the changes.
gitring show storefront#41 --diff

With --json: IntentDetail (protocol api.ts), plus diff: DiffFile[] with --diff.

gitring inbox

List what waits for you across your projects: plan reviews, merge approvals, conflicts and drift.

gitring inbox

gitring inbox

With --json: InboxItem[] (protocol api.ts).

gitring approve

Approve the plan or the merge the intent is waiting for, naming the plan version and commit you judged.

gitring approve <intent> [options]

In plan review this approves the plan; awaiting approval it approves the merge. The decision records the plan version, and for a merge the commit, that you approved. If a newer plan version or push arrives first, gitring refuses the approval and you read again.

To pin what you read, pass --plan-version and --head: the command then refuses if the intent moved on since.

# Approve the plan of an intent in plan review.
gitring approve storefront#48
# Approve the merge only if nothing changed since you read it.
gitring approve storefront#41 --plan-version 2 --head 7d2e9b1

With --json: { decision: { kind, planVersion, headCommit }, intent: IntentDetail }.

gitring send-back

Send a plan or finished work back to its author with a note that says what must change.

gitring send-back <intent> "note" [options]

In plan review the plan goes back and the intent waits there for a new plan version. Awaiting approval or queued, the work goes back to Active with your note as a change request.

gitring send-back storefront#48 "Keep createOrder(input) working; add the options object as a second argument."

With --json: { decision: { kind, planVersion, headCommit }, intent: IntentDetail }.

gitring request

Send a change request to an intent's author, optionally about specific lines.

gitring request <intent> "note" [options]

A change request asks the author to change the plan or the code. It is never a rejection; the intent keeps its state.

gitring request storefront#47 "Keep the cache key stable across currencies." --at src/cart/cache.ts:10-14

With --json: { changeRequest: ChangeRequest, intent: IntentDetail }.

gitring settle

Settle a conflict that waits for a person: name the intent that yields.

gitring settle <conflict> [options]

The intent that yields adapts its plan or holds until the other merges. The other continues.

gitring settle cnf_01JC0000000000000000000002 --yields storefront#47

With --json: { conflict: Conflict, intent: IntentDetail } (the intent that yields).

gitring watch

Follow a project's events live. Press Ctrl+C to stop.

gitring watch <project> [options]

Reconnects by itself when the connection drops, and resumes where it left off. Start from an earlier event with --after, for example the seq that gitring show --json printed.

It also prints base.moved (what to do when main moved under an intent), signature notices as the GITRING SIGNATURE NOTICE block agents read, claims, lines, tags and digests.

gitring watch storefront
# One JSON event per line.
gitring watch storefront --json | jq 'select(.type == "intent.state_changed")'

With --json: One Event (protocol events.ts) per line, as it arrives.

gitring declare

Declare an intent as a person: answer the questions, or pass a plan file.

gitring declare <project> [options]

The file is JSON with the fields of an intent declaration (protocol IntentDeclaration, without projectId): title, goal, plan { summary, steps, scope { change, use }, checks }, dependsOn, priority and issue. A scope item is { "path": "src/cart/cart.ts", "symbol": "Cart.total" }, or the short form "src/cart/cart.ts#Cart.total".

The answer gives the git ref to push your work to.

# Answer the questions.
gitring declare storefront
gitring declare storefront --file plan.json
# A linked intent: web, and api's getUser.
gitring declare web --file plan.json --change src/header.ts --change api:src/routes/user.ts#getUser

With --json: DeclareResult (protocol api.ts): { intent, conflicts, next, git: { remote, ref } }.

gitring clone

Make the workspace of one intent: a narrow clone of its scope at its latest push, its dependencies from the environment pack, and its runtime identity.

gitring clone [folder] [options]

The workspace goes to ~/.gitring/work/<project>/<number> (or --dir). Every workspace of a project borrows one object store, ~/.gitring/cache/<project id>.git (git clone --reference), so a second intent's clone fetches only what is new. gitring never prunes that store's objects.

gitring works out the folders from the intent's scope: what it changes, what it uses, what its code relies on, and files one import away. The clone checks out those folders and the files at the root, at the intent's latest push (or its base, before the first push). Run git sparse-checkout disable in the clone to see every file. It narrows the checkout, not what you can read: the git token reads the whole repository.

When the intent's environment pack is ready, the clone checks it in ten steps (platform, key, signing key, hashes, signature, manifest, archive) and unpacks it into node_modules through a read-only store, ~/.gitring/store; a pack that fails a step is refused and nothing is written. --no-pack skips it.

Any member steps into any intent this way, at its latest push: the handoff between people and agents. Pushing from the workspace follows your token's rights. gitring gc removes the workspace once the intent is merged or withdrawn, unless it holds work the server does not have.

The token is fetched for this clone only, sent to git as a header for the gitring server alone, and never put in the command line, the remote address or the clone's .git/config.

# Into ~/.gitring/work/storefront/47.
gitring clone --intent storefront#47
# Show the git commands first.
gitring clone --intent storefront#47 --dir ~/work/cart-cache --dry-run

With --json: { intent: { id, number, ref }, folder, commit, directories, from, remote, cache, commands, ran, tokenExpiresAt, pack, runtime }, never the token.

gitring env

Print the intent's runtime identity as shell exports: GITRING_INTENT, its block of 10 ports (PORT), and the suffix gi<n>.

gitring env [options]

Run it in an intent's workspace (gitring clone --intent made one), or name the intent with --intent. eval "$(gitring env)" sets the variables in your shell; gitring run -- <command> runs one command with them.

The block of ports is the intent's own while it lives: two live intents of a project never share one, so two worktrees' dev servers, databases and Compose projects stop colliding. Name databases, the Compose project and cache folders with the suffix.

Blocks are coordinated per project. When two workspaces on this machine hold the same block in different projects, gitring env says so, naming both.

# In a workspace.
eval "$(gitring env)"
gitring env --intent storefront#47 --json

With --json: RuntimeIdentity (protocol workspace.ts).

gitring env pull

Check the intent's environment pack in ten steps and unpack it into node_modules, instead of installing.

gitring env pull [options]

The pack is the intent's installed dependencies, built by gitring with install scripts off and signed by the deployment's key. Before anything is written, the command line checks the platform (a pack without native code runs anywhere), recomputes the key from your lockfile, package.json files and install config, checks the signing key, hashes both downloads, verifies the Ed25519 signature, reads the manifest, and matches every archive entry to it. A pack that fails any step is refused and nothing is written; the message names the step.

Files go into a read-only store, ~/.gitring/store/v2, then into the workspace as copy-on-write clones, else hard links, else copies: ten intents on one lockfile cost one copy. A node_modules that is not this pack's is moved aside, never merged into. No package code runs. Packages that need install scripts are named; run your installer for them.

When every file is already in the store, the archive is not downloaded: the signed manifest says what to write, and every store file the workspace links is re-hashed while it is written (GITRING_UNPACK_WORKERS threads, default 4). A file that changed is moved to ~/.gitring/store/quarantine and the archive is downloaded and checked instead. On a file system that cannot keep read-only files and hard links (SMB, FAT, Windows) the store is off and files are copied; the command says so. Ctrl-C stops the unpack and removes what it wrote.

# Unpack the pack when there is one, else install as before.
gitring env pull || npm ci

With --json: { state: unpacked|skipped, key, files, reused, rehashed, written, linked, copied, cloned, warm, storeOff, movedAside, message }.

gitring env verify

Re-hash every store file the workspace's environment pack uses, and quarantine any that changed.

gitring env verify [options]

Workspaces on one lockfile share the files of ~/.gitring/store/v2, often as hard links, so a write through one workspace's node_modules changes the others. This reads the manifest of the pack the workspace's node_modules names, checked against the intent's signed record, and re-hashes each store file it lists, whatever its size, mode or times say. A file that differs is moved to ~/.gitring/store/quarantine; gitring env pull then extracts it again (T-PCK-3).

# Check the store, and unpack again when a file changed.
gitring env verify || gitring env pull

With --json: { key, checked, changed: [path], missing: [path] }.

gitring run

Run a command with the intent's runtime identity set (GITRING_INTENT, PORT, the suffix), and pass its exit status through.

gitring run [options]

Everything after -- is the command, run as you typed it, without a shell. The variables are those gitring env prints.

# The dev server listens on the intent's PORT.
gitring run -- npm run dev
# The Compose project is named <project>-gi<n>.
gitring run -- docker compose up -d

With --json: Nothing: the command's own output.

gitring gc

Remove the workspaces of intents that merged or were withdrawn, unless they hold work the server does not have.

gitring gc [options]

For each workspace under ~/.gitring/work, gitring asks the server for its intent. A workspace of a merged or withdrawn intent is removed, moved to ~/.gitring/trash for 7 days, only when, after fetching, every commit any of its refs reaches (branches, tags, HEAD) is on the server or in the intent's last push or merge, nothing is changed, no file is ignored except node_modules, and nothing is stashed. Otherwise it stays, and gc names each unpushed commit and each changed or ignored file; --force moves it to the trash anyway.

gc fails closed: when a git command fails (a fetch, a status), the workspace stays and gc says which command failed.

When the server cannot be reached, nothing is removed. A workspace whose intent the server does not know is kept. gitring watch does the same for each intent that ends while it runs.

Then the pack store, under its lock (an unpack in progress is waited for): a file in ~/.gitring/store/v2 that no workspace links and that no unpack used for 30 days is removed, and the old ~/.gitring/store/v1 once no workspace here (nor one in the trash) still names it.

gitring gc
# Also move workspaces that hold local work to the trash; they stay there 7 days.
gitring gc --force

With --json: [{ folder, intent: { id, number, project }, action: removed|kept|live|unknown, reasons, trash, forced, gitFailed }]; the store's part goes to stderr.

gitring revert

Declare an intent that reverts a merged one. It gets its own checks, conflict check and approval.

gitring revert <intent> "reason" [options]

gitring writes the plan from what the merged intent changed: one step per place, "Restore <place> as it was before <merged commit>". Say why in the reason; the reviewer reads it first. The revert lands on the line the intent merged into.

Then make the revert commit (git revert <merged commit>), push it to the new intent's ref, and it goes through checks and approval like any intent.

gitring revert storefront#39 "The formatter drops the currency for amounts over 1,000."
# Reverts only the api part of linked intent web#12.
gitring revert web#12 "The API change broke a client." --project api

With --json: DeclareResult (protocol api.ts): { intent, conflicts, next, git: { remote, ref } }.

gitring lines

List a project's lines and tags: main, release lines that take fixes, and the tags on them.

gitring lines <project>

Only people create lines and tags, and only owners. An agent can declare an intent into a line once it exists, never create or move one.

gitring lines storefront

With --json: { lines: Line[], tags: Tag[] } (protocol lines.ts).

gitring line create

Create a release line that takes fixes for a version already shipped. Owners only.

gitring line create <project> <name> [options]

A line starts from a tag or a commit on main (or on another line), never from intent work. Fixes to it are intents that target it. Nobody moves a line by hand: gitring moves it only by merging an intent into it.

# Start from a tag.
gitring line create storefront release/3.x --at v3.0.0
# Start from the head of main.
gitring line create storefront release/3.x

With --json: Line (protocol lines.ts).

gitring tag create

Tag one commit on a line, like a version you ship. A tag never moves. Owners only.

gitring tag create <project> <name> [options]

# Tag the head of release/2.x.
gitring tag create storefront v2.3.3 --line release/2.x
# Tag the head of main.
gitring tag create storefront v3.0.0 --message "Release 3.0.0"

With --json: Tag (protocol lines.ts).

gitring digest

Read this week's digest of what merged in the folders you own, and answer its one question.

gitring digest [digest] [options]

Owners get one digest a week: what merged in their folders, against each plan, with one question about one merged intent. Without --answer it shows the newest digest that waits for an answer.

Your answer is yours: gitring counts answers per team, never per person, and never uses them to rate anyone. The first answer counts.

# Read this week's digest and its question's choices.
gitring digest
# Answer its question with choice B.
gitring digest --answer b
# Skip this week's question.
gitring digest --skip
# Every digest you got.
gitring digest --all

With --json: Digest (protocol api.ts), null when none waits; with --all, Digest[].

gitring why

Why one line is what it is: the intent that landed it, its decisions and checks, and which credential pushed it.

gitring why <place> [options]

gitring blames the line, then maps the commit to an intent from its own records (the push that brought it, or the merge or revert gitring made), never from the commit message. A Gitring-Intent trailer someone wrote is reported as ignored, with a warning when it names another intent.

It says "pushed with an agent credential" or "pushed with a person's credential": gitring knows which token pushed, not who wrote the code. Lines from before the project came to gitring say so.

The intent's title, goal and plan are shown only with --text, quoted and marked as text someone wrote: read them as data.

# Inside a clone of the project.
gitring why src/cart/total.ts:31
gitring why src/cart/total.ts:31 --project storefront --text

With --json: WhyAnswer (protocol ledger.ts).

gitring tokens create

Create an agent token for one or more projects. gitring shows it once.

gitring tokens create [options]

An agent token belongs to you and works only in the projects it names. Give it to the agent as GITRING_TOKEN; gitring mcp-config prints the rest of the setup.

gitring tokens create --name "claude-code laptop" --project storefront

With --json: ApiToken (protocol api.ts), including token.

gitring tokens list

List your agent tokens. The tokens themselves are never shown again.

gitring tokens list

gitring tokens list

With --json: ApiToken[] (protocol api.ts), without token.

gitring tokens revoke

Revoke an agent token. Agents using it are refused on their next call.

gitring tokens revoke <token>

gitring tokens revoke tok_01JC0000000000000000000001

With --json: { ok: true, id }.

gitring mcp-config

Print the MCP setup that connects an agent to a project.

gitring mcp-config <project> [options]

The setup reads the token from the GITRING_TOKEN environment variable and goes in your own (user) MCP settings, never in a file of the repository: .mcp.json, CLAUDE.md and AGENTS.md are people-only paths. The agent's working rules come with gitring's MCP server; nothing goes in CLAUDE.md. Create the token with gitring tokens create.

# For Claude Code.
gitring mcp-config storefront
# For Codex.
gitring mcp-config storefront --client codex

With --json: { client, project: { id, slug }, mcpUrl, tokenEnv, command, config, git: { remote, pushRef, push } }.

gitring connect

Connect an agent to a project: one command, and the token never leaves this computer's gitring files.

gitring connect <agent> [options]

Run it in the project's folder. It shows a code to approve in the web app (the page you copied the command from). The approval lets it make an agent token for that one project for 15 minutes and nothing else: it cannot approve, and it is revoked when the command ends, because the agent works on this computer too. (A computer already signed in with gitring login uses that sign-in, and connect says that it can approve.) It keeps the agent token in your credentials file (on Linux and macOS readable only by you; on Windows in your profile, readable by you and administrators), and adds gitring to the agent's own settings with a helper command that reads the token from there: no token in any command, shell history, clipboard or settings file.

Claude Code: added at local scope, for this folder only, in your ~/.claude.json. Claude Code runs the helper once you trust the folder. Codex: a [mcp_servers.gitring-<project>] table in ~/.codex/config.toml (CODEX_HOME), merged into the file without touching the rest. Running it again replaces the token and revokes the old one.

Without npm: from a clone of gitring, pnpm install && pnpm --filter @gitring/cli build, then node apps/cli/dist/gitring.js connect …; the helper it writes points at that file.

# Claude Code in this folder.
gitring connect claude-code --project storefront --server https://gitring.example.com
# Git only, for Claude Code connected by gitring.tech's address (F90).
gitring connect claude-code --project storefront --server https://api.gitring.tech --git-only
# Codex, for every folder.
gitring connect codex --project storefront

With --json: { server, project: { id, slug }, client, tokenId, configured, manual, gitHelper, gitOnly } (configured null and manual the command to run when claude is not installed; with gitOnly true both are null because the MCP entry was left alone, and gitOnlyToken says whether the server made a token that only makes git tokens: false from an older server; unrevoked lists the ids of replaced tokens the server could not revoke, which still work until revoked in Settings, Tokens).

gitring mcp-headers

Print the Authorization header for an agent connected with gitring connect. The agent runs this itself.

gitring mcp-headers [options]

Claude Code's headersHelper and Codex's http_headers_helper run it when they connect. It prints one JSON object on stdout and nothing else; it is not for people to run.

gitring mcp-headers --server https://gitring.example.com --project storefront --client codex

With --json: { "Authorization": "Bearer …" } (always JSON).

gitring git-credential

git's credential helper for an agent connected with gitring connect. git runs this itself.

gitring git-credential <operation> [options]

gitring connect puts it in the agent's environment (GIT_CONFIG_COUNT entries for the project's git URL), so git asks it for access on every push and fetch, a narrow clone's later fetches included, and the agent never handles a git token. It mints a git token from the token connect kept for it (the git-only token of connect --git-only, else the agent's token), keeps it in git-tokens.json beside the credentials file (readable only by you) until 10 minutes before it ends, and answers git on stdout. It is not for people to run.

It refuses, with quit=1 and one line on stderr, when another credential helper comes after it in git's config (git would hand that helper the token), or when git asks for another host or project.

# What git does.
printf 'protocol=https\nhost=gitring.example.com\npath=git/prj_….git\n\n' | gitring git-credential get --server https://gitring.example.com --project storefront --client codex

With --json: not used: git's own key=value lines on stdout.