rut-cli

CLI interface for Rut — Create and manage AI agent flows from the terminal.

Installation

# Install globally from npm
npm install -g rut-cli

# Or run directly with npx
npx rut-cli --help

Development Installation

# From the project root
cd tools/rut-cli
npm install
npm run build

# Link globally for development
npm link

Quick Start

# Create a new project
rut init my-project

# Add nodes with different agents
rut add "Fix the bug in auth.ts" --codex --title "Bug Fix"
rut add "Refactor the API handlers" --claude
rut add "Generate unit tests" --gemini --upstream "Bug Fix"

# List nodes
rut ls
rut ls -v  # verbose mode

# Show node details
rut show "Bug Fix"

# Create connections
rut connect "Bug Fix" "Refactor" --pass-context

# Remove a node
rut rm "Bug Fix"

Commands

Project Management

| Command | Description | |---------|-------------| | rut init [name] | Initialize a new project | | rut projects | List all projects | | rut open <project> | Switch to a project |

Node Operations

| Command | Description | |---------|-------------| | rut add <prompt> | Add a new node | | rut ls | List all nodes | | rut show <node> | Show node details | | rut rm <node> | Remove a node | | rut connect <from> <to> | Create a link between nodes |

Execution (Phase 2)

| Command | Description | |---------|-------------| | rut run [node] | Run the flow or a specific node |

Configuration

| Command | Description | |---------|-------------| | rut config show | Show current configuration | | rut config set <key> <value> | Set a configuration value | | rut config set-secret <key> | Set a secret value |

Agent Flags

| Flag | Short | Description | |------|-------|-------------| | --codex | -x | Use Codex agent (default) | | --claude | -c | Use Claude Code agent | | --gemini | -g | Use Gemini agent | | --mcp | -m | Use MCP Provider agent |

Examples

Create a Multi-Step Flow

# Initialize project
rut init refactor-project --repo /path/to/code

# Step 1: Analyze code
rut add "Analyze the current codebase structure and identify areas for improvement" \
  --codex --title "Analysis"

# Step 2: Refactor (depends on Step 1)
rut add "Refactor the identified areas following best practices" \
  --claude --upstream "Analysis" --pass-context --title "Refactor"

# Step 3: Write tests (depends on Step 2)
rut add "Write comprehensive tests for the refactored code" \
  --gemini --upstream "Refactor" --pass-context --title "Tests"

# Step 4: Review (depends on all previous)
rut add "Review all changes and provide a summary" \
  --codex --upstream "Analysis" "Refactor" "Tests" --title "Review"

# View the flow
rut ls -v

Using with Rut UI

Projects created with rut are fully compatible with the Rut visual interface:

1. Create a project: rut init my-flow
2. Add some nodes: rut add "..." --codex
3. Open the Rut app — your project appears automatically!
4. Make changes in the UI — they sync back to CLI

Development

# Watch mode for development
npm run dev

# Build
npm run build

# Run locally
node dist/bin/rut.js --help

# Link for global usage
npm link
rut --help

File Locations

• Projects: ~/.rut/projects/
• Config: ~/.rut/config.json
• Current project: ~/.rut/current

Roadmap

• [x] Phase 1: Core CLI (init, add, ls, show, rm, connect)
• [ ] Phase 2: Execution (run, agent spawning, context passing)
• [ ] Phase 3: Advanced features (flow shorthand, import/export)
• [x] Phase 4: Polish (npm publish ready)