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

> Master the rowboatlabs/rowboat CLI. This guide shows you how to manage AI agents, launch a TUI dashboard, and run interactive REPL sessions easily from your terminal.

- Repository: [RowBoat Labs/rowboat](https://github.com/rowboatlabs/rowboat)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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:

```bash
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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/config/config.ts) and contains:

- `agents/` — JSON definitions of imported agents
- [`config/models.json`](https://github.com/rowboatlabs/rowboat/blob/main/config/models.json) — LLM provider configuration selected via `model-config`
- [`config/mcp.json`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/app.ts) via the `app()` function.

### Basic Agent Execution

Run the default **copilot** agent:

```bash
rowboatx

```

Run a specific agent by name:

```bash
rowboatx --agent mybot

```

The CLI streams agent events in real-time and handles tool-permission prompts through the orchestration logic in [`src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/src/app.ts).

### Resuming Sessions and Non-Interactive Mode

Resume a previous conversation using the run ID:

```bash
rowboatx --run_id 123

```

Execute a single prompt without interactivity:

```bash
rowboatx --input "Explain quantum tunneling"

```

Disable all interactive prompts including tool permissions:

```bash
rowboatx --no-interactive

```

## Launching the TUI Dashboard

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

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

```

The TUI implementation resides in [`apps/cli/src/tui/index.tsx`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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:

```bash
rowboatx list-examples

```

This command calls `listExamples()` → `listAvailableExamples()` in [`src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/src/app.ts), which returns keys from the `examples` map defined in [`src/examples/index.ts`](https://github.com/rowboatlabs/rowboat/blob/main/src/examples/index.ts).

### Importing Workflows

Import a built-in example workflow:

```bash
rowboatx import --example twitter-podcast

```

Import a custom JSON workflow file:

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

```

The `importExample()` function in [`src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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:

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

```

The `exportWorkflow()` function in [`src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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:

```bash
rowboatx model-config

```

This runs the interactive wizard `modelConfig()` in [`src/app.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/src/models/repo.ts)

The dependency injection container in [`src/di/container.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/config/config.ts):

- **`agents/`** — JSON agent definitions imported via `importExample()`
- **[`config/models.json`](https://github.com/rowboatlabs/rowboat/blob/main/config/models.json)** — LLM configuration managed by `modelConfig()` and [`src/models/repo.ts`](https://github.com/rowboatlabs/rowboat/blob/main/src/models/repo.ts)
- **[`config/mcp.json`](https://github.com/rowboatlabs/rowboat/blob/main/config/mcp.json)** — MCP server definitions merged during import, validated against [`src/mcp/schema.ts`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/config/config.ts). This directory contains subdirectories for `agents/` (JSON agent definitions), [`config/models.json`](https://github.com/rowboatlabs/rowboat/blob/main/config/models.json) (LLM provider settings), and [`config/mcp.json`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/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`](https://github.com/rowboatlabs/rowboat/blob/main/apps/cli/src/models/repo.ts).