How to Use routa-cli for Terminal-First Workflows: Complete Command Reference

The routa-cli provides a unified terminal interface to Routa's core domain logic, enabling you to manage agents, tasks, and workflows via shell commands while maintaining full compatibility with the web UI and desktop client.

The routa-cli in the phodal/routa repository serves as the primary entry point for developers who prefer terminal-based interaction over graphical interfaces. Built on the Clap derive macro system (#[derive(Parser)]), this command-line interface exposes the full capabilities of routa-core and routa-server through intuitive subcommands. Using routa-cli for terminal-first workflows ensures that every operation—from agent creation to workflow execution—uses the same underlying RPC interfaces and SQLite state as the Next.js web UI and Tauri desktop client, guaranteeing cross-surface consistency across all three back-ends.

Architecture and State Management

The CLI reuses the identical core domain logic that powers the web and desktop surfaces. When you execute any command, routa-cli performs three critical initialization steps defined in crates/routa-cli/src/main.rs:

1. Initializes the shared SQLite state via commands::init_state(&cli.db).await
2. Injects environment variables (ROUTA_DB_PATH, PATH) so spawned ACP providers can locate binaries
3. Dispatches to the appropriate module (e.g., commands::agent::list, commands::task::create, commands::chat::run) which invokes underlying Routa core services via the same RPC interfaces used by graphical clients

Because the CLI talks directly to the on-disk data store, state changes are instantly visible to the web UI and desktop client. This architecture eliminates synchronization concerns when mixing terminal and graphical workflows.

Command Structure and Global Options

The Cli struct in crates/routa-cli/src/main.rs defines a hierarchical command structure using Clap's derive API. Global flags apply to all subcommands:

• --db: Path to the SQLite database file
• -p/--prompt: Quick one-shot prompt execution
• --version: Display version information

Available subcommands include acp, agent, task, kanban, workspace, skill, delegate, chat, scan, graph, fitness, workflow, review, team, and feature-tree.

Essential Commands for Terminal-First Workflows

Quick Prompts and One-Shot Generation

Execute immediate prompts without entering interactive mode:

# One-shot prompt for rapid code generation

routa -p "Design a login page with OAuth and dark mode"

# Check version and basic help

routa --version
routa --help

Agent Lifecycle Management

Manage autonomous agents directly from the terminal using commands implemented in crates/routa-cli/src/commands/agent.rs:

# List all agents in the default workspace (limits to 20 by default)

routa agent list

# Create a new developer-role agent named "alice"

routa agent create --name alice --role DEVELOPER

# Check ACP runtime status for debugging providers

routa acp runtime-status

Task Creation and Delegation

Create tasks and delegate them to specialist agents using implementations in crates/routa-cli/src/commands/task.rs and crates/routa-cli/src/commands/delegate.rs:

# Create a task with specific objectives

routa task create \
    --title "Implement login UI" \
    --objective "Provide OAuth login flow" \
    --workspace-id default

# Delegate to a specialist agent with immediate wait mode

routa delegate \
    --task-id <TASK_ID> \
    --caller-agent-id <CALLER_ID> \
    --caller-session-id <SESSION_ID> \
    --specialist CRAFTER \
    --provider opencode \
    --wait-mode immediate

Interactive Chat Sessions

Launch interactive conversations with specific agent roles using crates/routa-cli/src/commands/chat.rs:

# Start interactive chat with a developer-role agent

routa chat \
    --workspace-id default \
    --provider opencode \
    --role DEVELOPER

Workflow Automation

Execute YAML-defined workflows suitable for CI/CD pipelines using crates/routa-cli/src/commands/workflow.rs:

# Run a predefined workflow

routa workflow run --file deployment.yaml

Specialist Execution and Advanced Operations

Run domain-specific specialists with optional JSON output using crates/routa-cli/src/commands/specialist.rs:

# Run the crafter specialist for code generation

routa specialist run --specialist crafter \
    --prompt "Create a React component that fetches user data" \
    --workspace-id default

For Kanban board management, the CLI communicates with the Kanban JSON-RPC endpoint via crates/routa-cli/src/commands/kanban.rs, allowing terminal-based board updates that reflect immediately in the web UI.

Scripting with JSON-RPC

For automated pipelines, pipe JSON-RPC calls directly to the underlying server:

routa rpc --method agents.list --params '{"workspace_id":"default"}'

This interface exposes the internal RPC methods used by the web and desktop clients, enabling sophisticated automation scripts that interact with the exact same API surface.

Key Implementation Files

Understanding the source structure helps when extending or debugging routa-cli behavior:

• crates/routa-cli/src/main.rs: CLI entry point defining the Cli struct and command routing
• crates/routa-cli/src/commands/agent.rs: Implements agent list/create/run/status/summary
• crates/routa-cli/src/commands/task.rs: Implements task list/create/get/update-status
• crates/routa-cli/src/commands/acp/*.rs: Handles provider lifecycle management
• crates/routa-cli/src/commands/chat.rs: Interactive session management
• crates/routa-cli/src/commands/workflow.rs: YAML workflow execution engine
• crates/routa-cli/src/commands/specialist.rs: Specialist definition runner
• crates/routa-cli/src/commands/kanban.rs: Kanban board RPC client
• docs/platforms/cli.md: User-facing documentation covering installation and use cases

Summary

• The routa-cli provides terminal access to the same routa-core services used by the web UI and desktop client, ensuring state consistency across all interfaces.
• Built on Clap with derive macros, the CLI offers global flags (--db, -p) and comprehensive subcommands including agent, task, delegate, chat, and workflow.
• All commands initialize SQLite state via commands::init_state() and use the same RPC interfaces as graphical clients, making terminal workflows first-class citizens in the Routa ecosystem.
• The CLI supports both interactive use (chat sessions, quick prompts) and automation (JSON-RPC, YAML workflows), with full ACP runtime integration for agent delegation.

Frequently Asked Questions

How does routa-cli maintain compatibility with the web UI?

Because routa-cli initializes the same SQLite state via commands::init_state(&cli.db).await and dispatches to identical core service modules (e.g., commands::task::create), it uses the exact same RPC interfaces and data stores as the Next.js web UI. Any changes made via terminal appear instantly in the browser because both interfaces read from the same on-disk database.

Can I use routa-cli in CI/CD pipelines?

Yes, the CLI is designed for automation. Use the workflow subcommand to execute YAML-defined workflows, or pipe JSON-RPC calls directly using routa rpc --method agents.list --params '{}'. The tool injects necessary environment variables (ROUTA_DB_PATH, PATH) automatically when spawning ACP providers, making it suitable for headless server environments.

What is the difference between routa -p and routa chat?

The -p/--prompt flag executes a one-shot generation without entering interactive mode, ideal for single commands or scripts. The routa chat subcommand launches an interactive REPL session with persistent context, implemented in crates/routa-cli/src/commands/chat.rs, which maintains conversation state across multiple turns with an agent.

Where are the ACP provider commands implemented?

ACP (Agent Communication Protocol) operations such as runtime-status, install, and serve are implemented in the module hierarchy under crates/routa-cli/src/commands/acp/*.rs. These commands handle provider lifecycle management and binary resolution using the environment variables injected during CLI initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}