CLI Reference

Complete reference for the iron-rain command-line tool.

Installation

# Install globally
curl -fsSL https://raw.githubusercontent.com/howlerops/iron-rain/main/scripts/install.sh | bash

# Or install manually
npm install -g @howlerops/iron-rain-cli

# Or run without installing
npx @howlerops/iron-rain-cli

Commands

iron-rain

Launch the interactive TUI (terminal user interface).

iron-rain

If no config file is found, the onboarding wizard starts automatically — walking you through provider selection, API keys, and model slot assignment before saving iron-rain.json.

The TUI provides a branded terminal experience with color-coded model slots, per-message attribution, and keyboard-navigable model selection. Use the Settings screen to edit your configuration at any time.

iron-rain --headless <prompt>

Run a single prompt without the TUI. Useful for scripting and CI/CD.

iron-rain --headless "Explain this function"

Output format:

<model response>

[success] 142 tokens, 850ms

The prompt is dispatched to Cortex (main slot). Exit code is 0 on success, 1 on failure.

result=$(iron-rain --headless "Summarize this diff" 2>/dev/null)
echo "$result" | head -1

iron-rain config

Print the current resolved configuration as JSON. Useful for debugging.

iron-rain config

Shows the merged config after file discovery and environment variable resolution. If no config file is found, prints the defaults.

iron-rain models

List all models from the built-in provider registry.

iron-rain models

Output:

anthropic
  claude-opus-4-6
  claude-sonnet-4-20250514
  claude-haiku-4-5-20251001

openai
  gpt-4o
  o3
  o4-mini

ollama
  llama3.2
  qwen2.5-coder:32b
  ...

iron-rain --version

Print the version number.

iron-rain --version
# 0.1.0

iron-rain --help

Show usage information.

Slash Commands

Inside the TUI, type / to open the slash command menu. All available commands:

Session

Planning & Loops

Project Tools

Context & Memory

Skills & Tools

Model & Slot Info

System

Plan Workflow

Iron Rain has a built-in planner that generates a PRD and task breakdown, then executes tasks sequentially through the Forge slot.

Generate a plan

/plan Add user authentication with JWT tokens

This runs two LLM passes through Cortex:

1. PRD generation — produces a Product Requirements Document
2. Task breakdown — splits the PRD into executable tasks with titles, descriptions, acceptance criteria, and target files

Review and approve

After generation, the plan enters review mode. You can:

• Type approve (or a) — start execution
• Type reject (or r) — discard the plan
• Type edit <feedback> (or e <feedback>) — regenerate with your feedback

Execution

Once approved, tasks run sequentially. Each task gets the prior task's output as context. Plans support:

• Auto-commit — optional git commit after each task
• Pause/Resume — use /resume to continue a paused plan
• Saved plans — use /plans to list saved plans

Plans are stored in .iron-rain/plans/<id>/.

Iterative Loop

The loop command runs a task iteratively until a completion condition is met:

/loop Fix all failing tests --until "ALL TESTS PASSING"

Each iteration:

1. Runs the task through Forge with context from prior iterations
2. Checks if the completion condition is met via LLM evaluation
3. Stops when the condition is true or max iterations reached (default: 10)

If the loop detects it's stuck (3+ iterations with no progress), it automatically suggests a different strategy. Use /loop-pause and /loop-resume to control execution.

/context — manage context directories

Add external directories to your session's context scope. Files inside these directories can be referenced with @ mentions.

# Add a directory
/context add ../other-project

# List added directories
/context list

# Remove a directory
/context remove ../other-project

Directories are resolved to absolute paths and validated on add. They persist for the current session.

@ References

Use @ prefixes to inject files, directories, git state, or images into your prompt context.

File references

# Relative path (starts with ./ or ../)
@./src/index.ts explain this file

# Explicit file: prefix
@file:package.json what dependencies do we use?

File contents are injected into the system prompt wrapped in <file path="..."> tags. Maximum file size: 100KB.

Directory references

@dir:src/components/ what's the structure here?

Injects a listing of files and subdirectories, prefixed with d (directory) or f (file).

Git references

@git:diff what changed?
@git:status are there uncommitted files?
@git:log show recent commits

Supported git commands: diff, status, log, branch, stash. Each runs with a 5-second timeout.

Image references

@./screenshot.png what does this UI show?
@image:mockup.jpg implement this design

Images are read as base64 and passed to the model as multimodal content (when the provider supports it). Supported formats: PNG, JPG, JPEG, GIF, WebP, SVG. Maximum size: 20MB.

Slot routing

# Route to a specific slot (must be first word)
@cortex explain the architecture
@scout search for all TODO comments
@forge refactor this function

Slot routing (@cortex/@scout/@forge) is detected only when the @ token is a bare word at the start of the message. File-style references (@./, @file:, etc.) are always treated as context injection.

Multiple references

@./README.md @git:diff explain the recent changes relative to the README

You can combine multiple @ references in a single message. All resolved content is injected into the system prompt.

Mid-stream context injection

While the agent is streaming a response, you can type additional context and press Enter to inject it mid-stream:

1. The current stream is paused and the partial response is saved
2. Your new text is added as a user message
3. The agent resumes with the full updated history

Press Esc to cancel the stream entirely instead.

Project Init

The /init command analyzes your project and creates a knowledge base for Iron Rain:

/init

This command:

1. Generates a repo map — file tree with extracted symbols (functions, classes, exports)
2. Reads package.json for dependencies and project metadata
3. Detects config files (tsconfig.json, biome.json, Dockerfile, CI workflows, etc.)
4. Stores findings as persistent lessons in the session database
5. Dispatches an architecture review to the model with recommendations (only if warranted)

Run /init once when starting work on a new project. The stored lessons persist across sessions.

Code Review

Review code changes with structured feedback:

# Review staged changes
/review

# Review diff against a branch
/review main

The review prompt asks the model to evaluate changes for bugs, security vulnerabilities, performance issues, and style. Output includes severity ratings and specific line references.

Checkpoints & Undo

Iron Rain creates git-based checkpoints during plan execution. Use /undo to restore the last checkpoint:

/undo

Checkpoints are lightweight git commits that can be restored instantly. Each plan task creates a checkpoint before execution.

Flags

Config file resolution

The CLI searches for a config file in this order, starting from the current working directory and walking up to ~:

1. iron-rain.json
2. iron-rain.jsonc
3. .iron-rainrc.json

See Configuration for the full schema.

Exit codes