| name | crit-cli |
| description | Use when an agent needs to author or reply to crit inline comments programmatically (including multi-agent workflows commenting on shared code/plans/docs/proposals), publish or unpublish a crit review with crit share, sync a crit review to or from a GitHub PR or GitLab MR, or read/interpret a crit review JSON file. Covers crit comment, crit share, crit unpublish, crit pull, crit push, review file format, and resolution workflow. Not for invoking an interactive review loop — that's the `/crit` command. |
| user-invocable | false |
| agent | all |
Crit CLI Reference
If a plan was just written and the user said /crit or crit, invoke the /crit command — do not use this reference skill. This skill covers CLI operations like crit comment, crit pull/push, and crit share.
Comments have three scopes:
- Line comments (
scope: "line") — tied to specific lines, stored in files.<path>.comments
- File comments (
scope: "file") — about a file overall, stored in files.<path>.comments with start_line: 0
- Review comments (
scope: "review") — general feedback, stored in the top-level review_comments array
The review file path is shown by crit status.
Reading comments
When crit completes a review round, read stdout and follow its instructions. Unresolved comments are often embedded in that prompt as JSON. Check stderr for approved: true or approved: false.
When you need to read comments separately:
crit comments
crit comments --json
crit comments --all
crit comments --plan <slug>
crit comments [path]
Review-level comments are listed first — easy to miss in raw review.json. Uses the same review resolution as crit comment (--output, --plan, daemon session).
Multiple active sessions
When more than one review session matches the current directory and branch, headless commands (crit comment, crit comments, crit share, crit push, crit pull) refuse to guess. Run crit status (or crit status --json) to list every active session, then target the intended review with --session <id>:
crit comment --session <id> --author <name> <path>:<line> <body>
crit comment --session <id> --json --file comments.json --author <name>
crit comments --session <id>
crit share --session <id> <file>
crit push --session <id>
crit pull --session <id>
The JSON status output exposes the candidates in sessions.
{
"review_comments": [
{
"id": "r_f1e2d3",
"body": "Overall the architecture looks good",
"scope": "review",
"author": "User Name",
"resolved": false,
"replies": [
{ "id": "rp_b4a5c6", "body": "Thanks, addressed the minor issues", "author": "Gemini" }
]
}
],
"files": {
"path/to/file.go": {
"comments": [
{
"id"
Field rules:
resolved: false or missing — both mean unresolved. Only true means resolved.quote (optional): the specific text the reviewer selected — narrows scope within the line range. Focus changes on the quoted text rather than the entire range.anchor (line comments): full text of the commented lines when placed. When edits shift line numbers, locate content by anchor rather than trusting start_line/end_line.drifted: true: original content was removed or heavily rewritten — line numbers are approximate at best.- Unresolved comments may have
replies — read them before acting.
crit comment --author 'Gemini' '<body>'
crit comment --author 'Gemini' <path> '<body>'
crit comment --author 'Gemini' <path>:<line> '<body>'
crit comment --author 'Gemini' <path>:<start>-<end> '<body>'
crit comment --reply-to <id> --author 'Gemini' '<body>'
Hard rules:
- Always pass
--author 'Gemini' (or your agent name) so comments are attributed correctly.
- Always single-quote the body — double quotes break on backticks and shell metachars.
- Line numbers reference the file on disk (1-indexed), not diff line numbers.
- Reply bodies support markdown — use code fences and inline code where helpful.
- Only pass
--resolve when the user explicitly asks. Never resolve proactively.
Use --json for atomicity (single write, no partial state) and speed (one process). Two ways to feed the JSON:
echo '[
{"body": "overall feedback", "scope": "review"},
{"path": "session.go", "body": "restructure", "scope": "file"},
{"file": "src/auth.go", "line": 42, "body": "Missing null check"},
{"file": "src/auth.go", "line": "50-55", "body": "Extract to helper"},
{"reply_to": "c_a1b2c3", "body": "Fixed — added null check"},
{"reply_to": "r_f1e2d3", "body": "Done"}
]' | crit comment --json --author 'Gemini'
Prefer --file <path> for any multi-paragraph body. Shell-quoted JSON breaks the moment a "body" string contains a raw newline. Use write_file to author the JSON to a temp file, then point crit at it:
crit comment --json --file /tmp/replies.json --author 'Gemini'
--file - reads stdin (same as omitting the flag).
Per-entry schema:
| Field | Type | Required | Notes |
|---|
file / path | string | line/file comments | Relative path. path alone (no line) → file-level. |
line | int/string | line comments | 42 or "45-47" |
end_line | int | optional | Defaults to line |
body | string | always | |
author | string | optional | Per-entry override; falls back to --author |
scope | string | optional | "review" / "file" — usually inferred |
reply_to | string | replies | Comment ID (c_… or r_…) |
resolve | bool | optional | Only when user explicitly asks |
Scope inference (when scope omitted): has reply_to → reply; no file/path and no line → review-level; path but no line → file-level; file/path + line → line.
Comment IDs are unique per session, but the same ID can collide across files. Disambiguate with `--path`:
crit comment --reply-to c_a1b2c3 --path src/auth.go --author 'Gemini' 'Fixed the null check'
In --json mode, set the file field on the entry. Review-level IDs (r_…) are globally unique and never need this.
Plan reviews (via `crit plan` or the `exit_plan_mode` hook) store the review file in `~/.crit/plans//`. **Always pass `--plan `** — without it, `crit comment` looks in the project root and won't find the comments. The slug is shown in the review feedback prompt.
crit comment --plan my-plan-2026-03-23 --reply-to c_a1b2c3 --author 'Gemini' 'Updated the plan'
crit pull [number|url]
crit push [--dry-run] [--event <type>] [-m <msg>] [n]
crit pull --forge gitlab 42
Requires gh (GitHub) or glab (GitLab) installed and authenticated. Change number is auto-detected from the current branch when possible. Set "forge" / "gitlab_url" in config for self-managed hosts, or pass --forge.
--event values: comment (default), approve, request-changes. -m adds a review-level body message.
crit share <file> [file...]
crit share --share-url <url> <file>
crit share --qr <file>
crit share --org <slug> <file>
crit share --org <slug> --visibility unlisted <file>
crit unpublish [file...]
crit unpublish --share-url <url> [file...]
- No server needed — reads files directly from disk. If a review file exists, comments for the shared files are included automatically.
- Always relay the output — copy the URL (and QR if used) into your response. Don't make the user dig through tool output.
--qr is terminal-only — skip in mobile apps, web chat UIs, or anywhere Unicode block characters won't render correctly.--org <slug> shares under an organization. Visibility defaults to organization (members only). Override with --visibility (organization, unlisted, public).--share-url selects among configured share_targets (or overrides for one invocation). Required when multiple targets are configured and none is marked default. Empty CRIT_SHARE_URL= disables sharing for the process.- Unpublish uses the persisted delete token in the review file — no extra args needed unless targeting a non-default deployment with
--share-url.
