# How to Use tuicr Review CLI Commands for Scripting and Automation

> Automate code reviews with tuicr review CLI commands. Query, modify, and script review sessions non-interactively using JSON output. Boost your CI pipeline efficiency.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-02

---

**`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`](https://github.com/agavra/tuicr/blob/main/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

```bash
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:

```bash
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

```bash
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:

```bash
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:

```bash
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

```bash
#!/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

```yaml

# .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`](https://github.com/agavra/tuicr/blob/main/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:

```bash
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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.