CLI Commands Overview

Command Reference

Ralph TUI provides a comprehensive set of commands for managing autonomous AI agent execution. Each command serves a specific purpose in the workflow from setup to execution.

INFO

Use ralph-tui help to see all available commands, or ralph-tui <command> --help for detailed help on any specific command.

Available Commands

Command	Description
`ralph-tui`	Launch the interactive TUI
`ralph-tui run`	Start Ralph execution
`ralph-tui resume`	Resume an interrupted session
`ralph-tui status`	Check session status (headless, for CI/scripts)
`ralph-tui logs`	View/manage iteration output logs
`ralph-tui setup`	Run interactive project setup
`ralph-tui create-prd`	Create a new PRD interactively
`ralph-tui convert`	Convert PRD markdown to JSON format
`ralph-tui remote`	Manage remote server connections

Additional Commands

These commands help with configuration, plugin management, and diagnostics:

Command	Description
`ralph-tui config show`	Display merged configuration
`ralph-tui template show`	Display current prompt template
`ralph-tui template init`	Copy default template for customization
`ralph-tui template install`	Alias for template init
`ralph-tui skills list`	List bundled skills and installation status
`ralph-tui skills install`	Install skills to your agent's skills directory
`ralph-tui plugins agents`	List available agent plugins
`ralph-tui plugins trackers`	List available tracker plugins
`ralph-tui doctor`	Diagnose agent configuration issues
`ralph-tui info`	Display system information for bug reports
`ralph-tui docs [section]`	Open documentation in browser
`ralph-tui help`	Show help message

Typical Workflow

The commands are typically used in this order:

Setup

Run ralph-tui setup to configure your project. This creates the necessary configuration files and installs skills.

Create Tasks

Use ralph-tui create-prd to generate a PRD with AI assistance, or ralph-tui convert to convert an existing PRD to tasks.

Execute

Start execution with ralph-tui run. Ralph will work through your tasks autonomously.

Monitor & Resume

Check progress with ralph-tui status, review output with ralph-tui logs, and use ralph-tui resume if interrupted.

Command Categories

Execution Commands

run - Main execution command with full options for agent, tracker, and iteration control
resume - Continue from a saved session state
status - JSON-friendly status output for scripts and CI pipelines

PRD & Task Management

create-prd - AI-powered PRD creation with interactive chat mode
convert - Transform PRD markdown into executable task formats

Setup & Maintenance

setup - Interactive wizard for initial configuration
logs - View, filter, and clean up iteration logs

Diagnostics & Troubleshooting

doctor - Diagnose agent configuration and detect common issues
info - Display system information useful for bug reports (version, OS, agent status)

Remote Control

run --listen - Enable WebSocket server for remote control
remote - Manage connections to remote ralph-tui instances (add, remove, list, test, push-config)

INFO

Remote control allows you to monitor and manage ralph-tui instances running on servers, CI/CD environments, or other machines from a single TUI. See Remote Instance Management below for details.

Global Options

These options work with most commands:

Option	Description
`--help`, `-h`	Show help for the command
`--version`, `-v`	Show Ralph TUI version
`--cwd <path>`	Set working directory

Remote Instance Management

Control multiple ralph-tui instances running on different machines from a single TUI.

Quick Setup

On the remote machine (server):

Bash

# Start ralph with remote listener enabled
ralph-tui run --listen --prd ./prd.json
 
# Save the generated token shown on first run

On your local machine (client):

Bash

# Add the remote server
ralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...
 
# Test the connection
ralph-tui remote test prod
 
# Launch TUI to see tabs for local + remote instances
ralph-tui

Key Features

Tab-based navigation: Switch between instances with number keys (1-9) or [/]
Full control: Pause, resume, cancel, add/remove iterations on any instance
Config sync: Push your local configuration to remotes with ralph-tui remote push-config
Secure: Two-tier token authentication with automatic refresh
Resilient: Auto-reconnect with exponential backoff

For detailed documentation, see:

run --listen - Server-side remote control setup
remote - Client-side connection management

Next Steps

run - Learn about the main execution command
setup - Configure your project
create-prd - Create your first PRD
remote - Set up remote instance control