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

> Master routa-cli for terminal-first workflows. Manage agents tasks and workflows via shell commands with this complete command reference. Boost productivity today.

- Repository: [Fengda Huang/routa](https://github.com/phodal/routa)
- Tags: how-to-guide
- Published: 2026-05-26

---

**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](https://github.com/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`](https://github.com/phodal/routa/blob/main/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`](https://github.com/phodal/routa/blob/main/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:

```bash

# 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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/agent.rs):

```bash

# 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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/task.rs) and [`crates/routa-cli/src/commands/delegate.rs`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/delegate.rs):

```bash

# 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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/chat.rs):

```bash

# 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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/workflow.rs):

```bash

# 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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/specialist.rs):

```bash

# 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`](https://github.com/phodal/routa/blob/main/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:

```bash
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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/main.rs)**: CLI entry point defining the `Cli` struct and command routing
- **[`crates/routa-cli/src/commands/agent.rs`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/agent.rs)**: Implements `agent list/create/run/status/summary`
- **[`crates/routa-cli/src/commands/task.rs`](https://github.com/phodal/routa/blob/main/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`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/chat.rs)**: Interactive session management
- **[`crates/routa-cli/src/commands/workflow.rs`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/workflow.rs)**: YAML workflow execution engine
- **[`crates/routa-cli/src/commands/specialist.rs`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/specialist.rs)**: Specialist definition runner
- **[`crates/routa-cli/src/commands/kanban.rs`](https://github.com/phodal/routa/blob/main/crates/routa-cli/src/commands/kanban.rs)**: Kanban board RPC client
- **[`docs/platforms/cli.md`](https://github.com/phodal/routa/blob/main/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`](https://github.com/phodal/routa/blob/main/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.