consult - AI Consultation CLI

Query external AI models for reviews and analysis. Supports Gemini, Codex, and Claude.

Synopsis

consult -m <model> [options] consult stats [options]

The -m / --model flag is always required except for consult stats .

Models

Flag value Alias Notes

gemini

pro

Fast (~120-150s), file access via --yolo

codex

gpt

Thorough (~200-250s), shell exploration

claude

opus

Agent SDK with tool use (~60-120s)

All flags

-m, --model <model> Model to use (required except stats) --prompt <text> Inline prompt (general mode) --prompt-file <path> Prompt file path (general mode) --protocol <name> Protocol: spir, aspir, air, bugfix, tick, maintain -t, --type <type> Review type (see below) --issue <number> Issue number (required in architect context) --output <path> Save result to file --plan-phase <phase> Scope review to a plan phase (porch use) --context <path> Context file with feedback (porch use) --project-id <id> Project ID for metrics (porch use) --days <n> Stats: limit to last N days (default: 30) --project <id> Stats: filter by project ID --last <n> Stats: show last N invocations --json Stats: output as JSON

Review types (--type )

Type When to use

spec

Review a specification for completeness

plan

Review an implementation plan

impl

Review code implementation

pr

Review a pull request before merge

phase

Phase-scoped review (builder context only)

integration

Architect's integration review of a PR

Usage patterns

General query:

consult -m gemini --prompt "What's the best way to structure auth?" consult -m codex --prompt-file review-checklist.md

Protocol review:

consult -m gemini --type spec --issue 42 consult -m codex --type plan --issue 42 consult -m claude --type integration --issue 42

3-way parallel review (cmap): Always use --output for background runs — without it, results go to a temp file that may be garbage-collected.

consult -m gemini --type integration --issue 42 --output /tmp/cmap-gemini-42.md & consult -m codex --type integration --issue 42 --output /tmp/cmap-codex-42.md & consult -m claude --type integration --issue 42 --output /tmp/cmap-claude-42.md & wait

Stats:

consult stats # 30-day summary consult stats --days 7 --json # Last 7 days as JSON consult stats --project 42 # Filter by project

Rules

• -m is required for all non-stats commands

• --prompt and --type are mutually exclusive (different modes)

• --prompt and --prompt-file are mutually exclusive

• --protocol requires --type

• From architect context (outside .builders/ ), --issue is required for protocol reviews

• From builder context (inside .builders/ ), project auto-detects from porch state