How to Use the rowboatlabs/rowboat CLI: Complete Guide to AI Agent Management

The rowboatx CLI is the official command-line interface for the rowboatlabs/rowboat repository, enabling you to run AI agents in interactive REPL mode, launch a TUI dashboard, and manage complex workflows through simple terminal commands.

The rowboatlabs/rowboat CLI, located in the apps/cli directory of the repository, provides a comprehensive toolkit for developers building multi-agent systems. It supports everything from quick agent testing to production workflow deployment, with built-in support for multiple LLM providers and MCP (Model Context Protocol) servers.

Installation and Setup

Install the CLI globally from the repository or npm:

npm install -g @rowboatlabs/rowboatx

The CLI stores all user-specific data in a dedicated work directory at ~/.rowboat. This location is defined in apps/cli/src/config/config.ts and contains:

• agents/ — JSON definitions of imported agents
• config/models.json — LLM provider configuration selected via model-config
• config/mcp.json — Optional MCP server definitions used by workflows

Running AI Agents Interactively

The default rowboatx command launches an interactive REPL with the specified agent, implemented in apps/cli/src/app.ts via the app() function.

Basic Agent Execution

Run the default copilot agent:

rowboatx

Run a specific agent by name:

rowboatx --agent mybot

The CLI streams agent events in real-time and handles tool-permission prompts through the orchestration logic in src/app.ts.

Resuming Sessions and Non-Interactive Mode

Resume a previous conversation using the run ID:

rowboatx --run_id 123

Execute a single prompt without interactivity:

rowboatx --input "Explain quantum tunneling"

Disable all interactive prompts including tool permissions:

rowboatx --no-interactive

Launching the TUI Dashboard

The CLI includes a visual terminal user interface built with Ink (React for terminals). Launch it with:

rowboatx ui --server-url https://my.rowboat.server

The TUI implementation resides in apps/cli/src/tui/index.tsx and provides a dashboard view of your agents and workflows. The command entry point is defined in apps/cli/bin/app.js using yargs for argument parsing.

Workflow Management

The CLI supports importing pre-built examples and exporting your complete workflow configurations.

Listing Available Examples

View all bundled workflow examples:

rowboatx list-examples

This command calls listExamples() → listAvailableExamples() in src/app.ts, which returns keys from the examples map defined in src/examples/index.ts.

Importing Workflows

Import a built-in example workflow:

rowboatx import --example twitter-podcast

Import a custom JSON workflow file:

rowboatx import --file ./my-workflow.json

The importExample() function in src/app.ts handles the import process:

1. Loads the example definition from examples/<name>.json or user file
2. Writes each agent to ~/.rowboat/agents/ via writeAgents()
3. Merges MCP server definitions into ~/.rowboat/config/mcp.json via mergeMcpServers()
4. Prints the command to run the entry agent

Exporting Workflows

Export a complete workflow including all dependencies:

rowboatx export --agent my-entry-agent > workflow.json

The exportWorkflow() function in src/app.ts walks the agents/ directory, resolves transitive agent dependencies and referenced MCP servers, then outputs a single JSON document compatible with importExample().

Configuring LLM Providers

Configure which LLM provider and model your agents use:

rowboatx model-config

This runs the interactive wizard modelConfig() in src/app.ts, which:

• Displays the current provider/model from ~/.rowboat/config/models.json
• Lets you select a provider flavor (OpenAI, Anthropic, Google, Ollama, etc.)
• Prompts for alias, base URL, API key (or environment variable reference), and model name
• Persists configuration via the model repository in src/models/repo.ts

The dependency injection container in src/di/container.ts (using Awilix) resolves the model-config repository service used throughout the CLI.

Configuration Directory Structure

The CLI maintains state in ~/.rowboat as defined in apps/cli/src/config/config.ts:

• agents/ — JSON agent definitions imported via importExample()
• config/models.json — LLM configuration managed by modelConfig() and src/models/repo.ts
• config/mcp.json — MCP server definitions merged during import, validated against src/mcp/schema.ts using Zod schemas

Summary

• The rowboatx CLI provides terminal-based interaction with the rowboatlabs/rowboat multi-agent framework through commands defined in apps/cli/bin/app.js.
• Run agents interactively using rowboatx or rowboatx --agent <name>, with optional non-interactive mode via --input or --no-interactive.
• Manage workflows by importing examples (import --example) or custom JSON (import --file), and export complete configurations via export --agent.
• Configure LLM providers through the interactive model-config wizard, which persists settings to ~/.rowboat/config/models.json.
• All user data resides in the ~/.rowboat work directory, with agents stored in agents/ and MCP configurations in config/mcp.json.

Frequently Asked Questions

How do I install the rowboatlabs/rowboat CLI?

Install the CLI globally using npm with the command npm install -g @rowboatlabs/rowboatx. Once installed, the rowboatx command becomes available in your terminal, allowing you to run agents, launch the TUI dashboard, and manage workflows immediately.

Where does the rowboatx CLI store configuration files?

The CLI stores all user-specific data in a dedicated work directory located at ~/.rowboat, as defined in apps/cli/src/config/config.ts. This directory contains subdirectories for agents/ (JSON agent definitions), config/models.json (LLM provider settings), and config/mcp.json (MCP server configurations).

Can I run the rowboatx CLI without interactive prompts?

Yes, you can execute agents non-interactively using the --input flag to provide a single prompt, or the --no-interactive flag to disable all tool permission prompts and human input requests. These options are handled by the app() function in apps/cli/src/app.ts and are useful for scripting and automation scenarios.

How do I add a custom LLM provider to the rowboatx CLI?

Run the interactive configuration wizard with rowboatx model-config, which prompts you to select a provider flavor (OpenAI, Anthropic, Google, Ollama, etc.), specify the base URL, API key or environment variable, and model name. The modelConfig() function in apps/cli/src/app.ts persists these settings to ~/.rowboat/config/models.json via the repository pattern implemented in apps/cli/src/models/repo.ts.

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