Installation

Install and configure the rowboatx CLI tool

Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Version 8.0.0 or higher (comes with Node.js)
• Operating System: macOS, Linux, or Windows

Installation Methods

NPM (Recommended)

Install globally using npm:

npm install -g @rowboatlabs/rowboatx

Verify the installation:

rowboatx --version
# Output: 0.16.0

From Source

Clone and build from source:

1. Clone the repository

   git clone https://github.com/rowboatlabs/rowboat.git
   cd rowboat/apps/cli
   
2. Install dependencies

   pnpm install
   
3. Build the project

   pnpm build
   
4. Link globally

   npm link
   

Initial Configuration

Configure LLM Provider

After installation, configure your LLM provider:

rowboatx model-config

This launches an interactive wizard:

1. Select provider type

   Choose from available providers:

   OpenAI

   1. openai
   2. anthropic
   3. google
   4. ollama
   5. openai-compatible
   6. openrouter
   7. aigateway
   8. rowboat [free]
   
2. Enter provider details

   Provide configuration based on the selected provider:

   Provider Name · string · required

   Alias for this provider configuration (e.g., “my-openai”)

   Base URL · string

   API endpoint URL. Defaults to provider’s standard endpoint.

   Examples:

   • OpenAI: https://api.openai.com/v1
   • Ollama: http://localhost:11434
   • Custom: http://localhost:8080/v1

   API Key · string

   Authentication key for the provider. Leave blank to use environment variable.

   Environment variables:

   • OpenAI: OPENAI_API_KEY
   • Anthropic: ANTHROPIC_API_KEY
   • Google: GOOGLE_GENERATIVE_AI_API_KEY

   Model · string · required

   Model identifier to use with this provider.

   Examples:

   • OpenAI: gpt-5.1, gpt-4o
   • Anthropic: claude-sonnet-4-5, claude-opus-4
   • Google: gemini-2.5-pro
   • Ollama: llama3.1, mistral
3. Verify configuration

   Configuration is saved to ~/.rowboat/config/models.json:

   {
     "providers": {
       "my-openai": {
         "flavor": "openai",
         "apiKey": "sk-...",
         "baseURL": "https://api.openai.com/v1"
       }
     },
     "defaults": {
       "provider": "my-openai",
       "model": "gpt-5.1"
     }
   }
   

Configure MCP Servers (Optional)

To use MCP (Model Context Protocol) servers, create ~/.rowboat/config/mcp.json:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

Provider-Specific Setup

OpenAI

Environment Variable

export OPENAI_API_KEY="sk-..."
rowboatx model-config

Anthropic

Environment Variable

export ANTHROPIC_API_KEY="sk-ant-..."
rowboatx model-config

Ollama (Local)

1. Install Ollama

   Download from ollama.ai or install via package manager:

   # macOS
   brew install ollama
   
   # Linux
   curl -fsSL https://ollama.ai/install.sh | sh
   
2. Pull a model

   ollama pull llama3.1
   
3. Configure rowboatx

   rowboatx model-config
   # Select: ollama
   # Base URL: http://localhost:11434 (default)
   # Model: llama3.1
   

Google AI

export GOOGLE_GENERATIVE_AI_API_KEY="AIza..."
rowboatx model-config
# Select: google
# Model: gemini-2.5-pro

Verification

Test your installation:

# Run default agent
rowboatx --input "Hello, what can you help me with?"

# Check configuration
cat ~/.rowboat/config/models.json

Troubleshooting

Command not found: rowboatx

Ensure the global npm bin directory is in your PATH:

npm config get prefix
# Add <prefix>/bin to your PATH
export PATH="$(npm config get prefix)/bin:$PATH"

Permission denied errors

Fix npm permissions or use a Node version manager:

# Option 1: Fix npm permissions
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Option 2: Use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
npm install -g @rowboatlabs/rowboatx

API key not being recognized

Verify environment variables are set:

echo $OPENAI_API_KEY
# Should output your key

# Or configure directly
rowboatx model-config

MCP servers not connecting

Check MCP server configuration:

# Verify mcp.json syntax
cat ~/.rowboat/config/mcp.json | jq .

# Test server command manually
npx -y @modelcontextprotocol/server-filesystem /tmp

Updating

Update to the latest version:

npm update -g @rowboatlabs/rowboatx

Uninstallation

Remove the CLI:

# Uninstall package
npm uninstall -g @rowboatlabs/rowboatx

# Optionally remove configuration
rm -rf ~/.rowboat

Next Steps

Command Reference

Explore all available commands and options