How to Use tuicr Review CLI Commands for Scripting and Automation

tuicr review provides non-interactive JSON-based commands that let scripts and CI pipelines query, modify, and automate code review sessions without launching the TUI.

The tuicr terminal user interface for code reviews includes a dedicated CLI subcommand designed specifically for automation. These scripting primitives in src/review_cli.rs expose every review operation—listing sessions, reading comments, and adding feedback—as composable, machine-readable interfaces. This guide covers all tuicr review CLI commands with production-ready patterns for shell scripts and CI/CD integration.

tuicr review CLI Command Overview

Unlike the interactive TUI, the tuicr review subcommand operates entirely through flags and JSON. All commands output structured data and accept deterministic inputs, making them ideal for:

• Pre-commit hooks that validate review coverage
• CI jobs that append automated analysis results
• Bots that synchronize comments with external systems

The CLI distinguishes between local sessions (path-based slugs like owner/repo@branch/worktree) and PR sessions (forge-based slugs like gh:owner/repo/pr/1234).

Core Commands

Command	Purpose	Output Format
tuicr review list	Enumerate stored sessions	JSON array with metadata
tuicr review comments	Retrieve all comments from a session	JSON array of comment records
tuicr review add	Insert a new comment	None (exit code only)

Listing and Discovering Review Sessions

Use tuicr review list to locate active or historical sessions for automation targets.

The --repo selector accepts three formats:

• . — current checkout path
• owner/repo — forge coordinate
• --all — scan every known repository

Active Session Filtering

tuicr review list --repo . | jq '.[] | select(.active) | {slug, updated_at}'

Output includes RFC 3339 timestamps and an active boolean indicating whether a live TUI instance holds the session. The slug field provides the session identifier required by other commands.

PR Session Targeting

When working with pull requests, forge-based slugs are self-contained—the --repo flag is ignored:

tuicr review list --repo . | jq -r '.[].slug' | grep '^gh:'

Reading Comments Programmatically

The tuicr review comments --session <slug> command exports complete comment histories as JSON. Each record contains:

• location — file path with optional line information
• side — "old" or "new" (pre/post change)
• type — "issue", "suggestion", "note", "praise", etc.
• state — lifecycle status
• created_at — ISO timestamp

Structured Comment Extraction

SESSION="gh:octocat/example/pr/42"
tuicr review comments --session "$SESSION" | \
  jq -r '.[] | "\(.location): \(.content) [\(.comment_type)]"'

This pattern enables integration with notification systems, report generators, or compliance checkers requiring review state inspection.

Adding Comments: Flags vs. JSON Input

tuicr review add supports two input modes controlled by the presence of --input.

Flag-Based Quick Inserts

For single comments with explicit parameters:

tuicr review add \
  --session "$SESSION" \
  --target-file src/lib.rs \
  --line 42 \
  --side new \
  --type issue \
  "Explain why this magic number is unsafe."

Required flags: --session, --target-file, --line Optional flags: --side (default: new), --type (default: note)

JSON Payload Mode for Automation

For batch operations or complex targets like line ranges, use --input with a file matching the AddCommentRequest structure:

cat > payload.json <<'EOF'
{
  "type": "suggestion",
  "content": "Consider using `Iterator::map` here.",
  "target": {
    "type": "line",
    "file": "src/main.rs",
    "line": 10,
    "side": "new"
  }
}
EOF

tuicr review add --session "$SESSION" --input payload.json

The target.type field supports "line" or "line_range". For ranges, specify start_line and end_line instead of line.

Batch Automation Patterns

Auto-Comment TODO Discovery

#!/usr/bin/env bash
set -euo pipefail

SESSION=$(tuicr review list --repo . | jq -r '.[0].slug')

for file in src/*.rs; do
  start=$(grep -n "TODO" "$file" | cut -d: -f1 | head -n1)
  [ -z "$start" ] && continue
  
  end=$((start + 3))

  jq -n \
    --arg content "Review TODO block: $(sed -n "${start}p" "$file" | xargs)" \
    --arg file "$file" \
    --argjson start "$start" \
    --argjson end "$end" \
    '{
      type: "issue",
      content: $content,
      target: {
        type: "line_range",
        file: $file,
        start_line: $start,
        end_line: $end,
        side: "new"
      }
    }' | tuicr review add --session "$SESSION" --input /dev/stdin
done

This pattern locates TODO markers, extracts context, and files review comments automatically.

CI/CD Integration Example

# .github/workflows/review-bot.yml

name: Automated Review Sign-off

jobs:
  approve:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Install tuicr
        run: cargo install --git https://github.com/agavra/tuicr
        
      - name: Append automated approval
        run: |
          SESSION=$(tuicr review list --repo . | jq -r '.[0].slug // empty')
          [ -z "$SESSION" ] && exit 0
          
          tuicr review add \
            --session "$SESSION" \
            --type praise \
            "CI passed: all tests, lints, and security scans successful."

Session Synchronization Behavior

CLI modifications write immediately to the session file in src/persistence/storage.rs. Concurrent TUI instances detect changes through the polling mechanism controlled by review_watch_interval_ms (configuration key). There is no locking protocol—last-write-wins semantics apply.

Error Handling and Exit Codes

Condition	Exit Code	jq Handling
Success	0	Parse normally
Session not found	1	Empty output or error to stderr
Invalid JSON input	2	Pre-validate with jq empty
Permission denied	1	Check file ownership in ~/.local/share/tuicr/

Defensive scripts should validate before piping:

tuicr review list --repo . | jq -e 'length > 0' >/dev/null || exit 1

Summary

• tuicr review list discovers sessions with JSON output including active flags and RFC 3339 timestamps; --repo accepts paths, forge coordinates, or --all
• tuicr review comments exports complete comment histories with location, side, type, and state metadata
• tuicr review add accepts flags for single comments or --input JSON matching AddCommentRequest for programmatic batches
• PR sessions use self-contained forge slugs (gh:owner/repo/pr/N); local sessions use path-based slugs
• Immediate persistence means CLI changes reflect in running TUI instances after the next poll interval
• All I/O is JSON, enabling jq transformation and Unix pipeline composition

Frequently Asked Questions

How do I find the session slug for the current pull request?

Run tuicr review list --repo . | jq -r '.[].slug | select(startswith("gh:"))' to extract forge-based session identifiers. If the PR was never opened in tuicr, no session exists yet—you must create one through the TUI first.

Can multiple scripts write to the same session simultaneously?

Yes, but with caveats. The storage layer in src/persistence/storage.rs performs atomic reads and writes, yet concurrent modifications may result in lost updates. For high-frequency automation, serialize access or implement external coordination.

What JSON schema does --input require for tuicr review add?

The payload must match AddCommentRequest as defined in src/model/review.rs. Required fields: type (string), content (string), target (object). The target object requires type, file, and side; use line for single-line comments or start_line/end_line for ranges.

Why does my CI job fail to find sessions?

Sessions are stored per-user in ~/.local/share/tuicr/ (or platform equivalent). CI runners using fresh environments lack persisted state. Either mount a cache volume or use PR-based slugs (gh:owner/repo/pr/N) which tuicr can resolve against the forge API without local session files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}