Rowbound

A CLI for GTM Engineering in Google Sheets with Claude Code.

Demo

Install

Prerequisites

• Node.js 22+ — node --version must be >= 22.0.0
• gws CLI — Google Workspace CLI for Sheets access

npm install -g @googleworkspace/cli
gws auth setup   # first time: creates Cloud project, enables APIs, logs in
gws auth login   # subsequent logins

Quick install

npm install -g github:eliasstravik/rowbound

Build from source

git clone https://github.com/eliasstravik/rowbound.git
cd rowbound
npm install
npm run dev -- <command>

Quick Start

# 1. Initialize a sheet
rowbound init <spreadsheet-id>

# 2. Add an action
rowbound config add-action <spreadsheet-id> --json '{
  "id": "enrich_company",
  "type": "http",
  "target": "company_info",
  "method": "GET",
  "url": "https://api.example.com/company?domain={{row.domain}}",
  "headers": { "Authorization": "Bearer {{env.API_KEY}}" },
  "extract": "$.name"
}'

# 3. Store API keys and run
rowbound env set API_KEY=your_key_here
rowbound run <spreadsheet-id>
rowbound run <spreadsheet-id> --dry-run   # preview first

Column names are automatically resolved to stable IDs when you run rowbound sync.

Features

Sources — Create rows from external data

• HTTP sources — fetch from any API, extract array from response, map columns via JSONPath
• Exec sources — run shell commands, parse JSON output into rows
• Script sources — run named scripts to generate rows from their output
• Webhook sources — accept inbound POST payloads, create rows in real-time
• Deduplication — skip or update existing rows based on a match column
• Scheduling — run sources manually, hourly, daily, or weekly

Actions — Enrich existing rows

• HTTP actions — call any REST API with templated URLs, headers, and bodies; extract values with JSONPath; ifEmpty fallback when extract returns nothing
• Waterfall actions — try multiple providers in order until one returns a result (e.g., Clearbit → Apollo → Hunter)
• Formula actions — compute derived values with JavaScript expressions using {{Column Name}} references
• AI actions — run headless Claude or Codex per row with configurable model, max turns, tools, and bare mode for faster startup
• Exec actions — run shell commands and capture stdout
• Script actions — run reusable named scripts stored in config; supports bash, python3, and node runtimes
• Lookup actions — pull data from other tabs (boolean, count, or full row JSON)
• Write actions — push data to other tabs with column mapping; supports append, upsert, and array expansion via expandPath
• Per-action environment variables — inject env vars per action (e.g., PLAYWRIGHT_HEADLESS=true)

Pipeline

• Conditional execution — skip actions per-row with when expressions
• Smart skip — automatically skips rows where the target cell already has a value
• Watch mode — poll sheets on an interval or trigger runs via webhook
• Column tracking — stable column IDs that survive header renames and reordering
• --columns flag — target specific columns by letter (e.g., --columns A-C,E,AP)
• --rows flag — flexible row specs (e.g., --rows 2-5,8,10-12)
• Rate limiting — configurable seconds between requests (default: 1 per second)
• Timeouts in seconds — all user-facing timeouts in seconds, not milliseconds
• Retry with backoff — exponential, linear, or fixed backoff on failures
• Structured error handling — per-action onError config maps status codes to actions (skip, write fallback)
• MCP server — expose all operations as Model Context Protocol tools for Claude Desktop and other AI assistants
• Run history — track pipeline executions with per-action summaries, durations, and error logs
• Dry run — preview what would change without writing to the sheet
• Per-tab stop/start — enable or disable processing per tab; stops mid-run if toggled during execution
• Per-tab settings — override concurrency, rate limit, retries, and backoff per tab
• BYOK — bring your own API keys, pay only for the APIs you use

CLI Commands

MCP Server

Rowbound exposes all pipeline operations as MCP tools. Add this to your Claude Desktop config:

{
  "mcpServers": {
    "rowbound": {
      "command": "rowbound",
      "args": ["mcp"]
    }
  }
}

Source Types

Sources create rows from external data. They run before actions in the pipeline — new rows are created first, then actions enrich them on the next run.

http source

Fetch from an API and create rows from the response.

{
  "id": "search_companies",
  "type": "http",
  "method": "POST",
  "url": "https://api.blitz-api.ai/v2/search/company",
  "headers": { "x-api-key": "{{env.BLITZ_API_KEY}}" },
  "body": { "industry": "restaurants", "country_code": ["SE"] },
  "extract": "$",
  "extractPath": "$.results",
  "columns": { "Title": "$.company_name", "Website": "$.website_url", "LinkedIn": "$.linkedin_url" },
  "dedup": "Website",
  "schedule": "daily"
}

exec source

Run a shell command and parse JSON output into rows.

{
  "id": "import_leads",
  "type": "exec",
  "command": "curl -s https://api.example.com/leads",
  "extract": "$.data",
  "columns": { "Name": "$.name", "Email": "$.email" },
  "dedup": "Email",
  "updateExisting": true
}

webhook source

Accept inbound POST payloads and create rows. Used with rowbound watch.

{
  "id": "form_submissions",
  "type": "webhook",
  "columns": { "Name": "$.name", "Email": "$.email", "Company": "$.company" },
  "dedup": "Email"
}

Source options

script source

Run a named script (defined in the scripts config section) and parse its output into rows.

{
  "id": "import_from_script",
  "type": "script",
  "script": "fetch_leads",
  "args": ["--format", "json"],
  "extract": "$.leads",
  "columns": { "Name": "$.name", "Email": "$.email" },
  "dedup": "Email"
}

Scripts

Scripts are reusable code blocks stored in your pipeline config. Define a script once, then reference it from multiple actions or sources by name. Each script has a runtime (the interpreter) and code (the script body).

Config section

Scripts are stored under the scripts key in your config (global or per-tab):

{
  "scripts": {
    "claude_json": {
      "runtime": "bash",
      "code": "#!/bin/bash\ncurl -s https://api.anthropic.com/v1/messages \\\n  -H \"x-api-key: $ANTHROPIC_API_KEY\" \\\n  -H \"content-type: application/json\" \\\n  -d \"$1\""
    },
    "parse_csv": {
      "runtime": "python3",
      "code": "import csv, json, sys\nwith open(sys.argv[1]) as f:\n    print(json.dumps(list(csv.DictReader(f))))"
    }
  }
}

Supported runtimes: bash, python3, node.

Referencing scripts from actions

Use "type": "script" in an action to run a named script per row. The script receives row data via template-expanded arguments and its stdout is captured as the result.

{
  "id": "enrich_with_claude",
  "type": "script",
  "target": "ai_summary",
  "script": "claude_json",
  "args": ["{\"model\":\"claude-sonnet-4-20250514\",\"max_tokens\":256,\"messages\":[{\"role\":\"user\",\"content\":\"Summarize: {{row.company}}\"}]}"],
  "extract": "$.content[0].text",
  "timeout": 60000
}

Referencing scripts from sources

Use "type": "script" in a source to run a named script and create rows from its output.

{
  "id": "load_leads",
  "type": "script",
  "script": "parse_csv",
  "args": ["/tmp/leads.csv"],
  "columns": { "Name": "$.name", "Email": "$.email" },
  "dedup": "Email"
}

CLI commands

Action Types

Templates use {{row.column}} for row data and {{env.KEY}} for environment variables. Actions support conditional execution with when expressions and structured error handling with onError.

http

Call a REST API and extract a value with JSONPath.

{
  "id": "get_company",
  "type": "http",
  "target": "company_name",
  "when": "row.domain !== ''",
  "method": "GET",
  "url": "https://api.clearbit.com/v2/companies/find?domain={{row.domain}}",
  "headers": { "Authorization": "Bearer {{env.CLEARBIT_API_KEY}}" },
  "extract": "$.name",
  "ifEmpty": "❌",
  "onError": { "404": "skip", "429": "skip", "default": { "write": "ERROR" } }
}

waterfall

Try multiple providers in order. First non-empty result wins.

{
  "id": "find_email",
  "type": "waterfall",
  "target": "email",
  "providers": [
    {
      "name": "hunter",
      "method": "GET",
      "url": "https://api.hunter.io/v2/email-finder?domain={{row.domain}}&first_name={{row.first_name}}&last_name={{row.last_name}}&api_key={{env.HUNTER_API_KEY}}",
      "extract": "$.data.email"
    },
    {
      "name": "apollo",
      "method": "POST",
      "url": "https://api.apollo.io/api/v1/people/match",
      "headers": { "Content-Type": "application/json", "X-Api-Key": "{{env.APOLLO_API_KEY}}" },
      "body": { "email": "{{row.personal_email}}", "domain": "{{row.domain}}" },
      "extract": "$.person.email"
    }
  ]
}

formula

Compute a value with a sandboxed JavaScript expression.

{
  "id": "full_name",
  "type": "formula",
  "target": "full_name",
  "expression": "`${row.first_name} ${row.last_name}`"
}

exec

Run a shell command and capture stdout. Template values are shell-escaped.

{
  "id": "whois_lookup",
  "type": "exec",
  "target": "registrar",
  "command": "whois {{row.domain}} | grep 'Registrar:' | head -1 | cut -d: -f2",
  "timeout": 10000,
  "onError": { "default": "skip" }
}

lookup

Pull data from another tab by matching a column value. Source tab data is cached per pipeline run for performance.

{
  "id": "get_company_info",
  "type": "lookup",
  "target": "company_name",
  "sourceTab": "Companies",
  "matchColumn": "Domain",
  "matchValue": "{{row.domain}}",
  "matchOperator": "equals",
  "returnColumn": "Name",
  "matchMode": "first"
}

Use "matchMode": "all" to return all matches as a JSON array. Use "matchOperator": "contains" for substring matching.

write

Push data to another tab with column mapping. Supports append, upsert, and array expansion.

{
  "id": "export_contacts",
  "type": "write",
  "target": "export_status",
  "destTab": "Contacts",
  "columns": {
    "Company": "{{row.company}}",
    "Name": "{{item.name}}",
    "Title": "{{item.title}}",
    "Email": "{{item.email}}"
  },
  "expand": "{{row.contacts_json}}",
  "expandPath": "$.contacts"
}

• append (default) — always create new rows
• upsert — update existing rows if upsertMatch column matches, otherwise append
• expand + expandPath — expand a JSON array into multiple rows; use {{item.field}} in column templates to access element data

script

Run a named script and capture its output. Scripts are defined in the scripts config section and referenced by name.

{
  "id": "ai_summary",
  "type": "script",
  "target": "summary",
  "script": "claude_json",
  "args": ["{\"prompt\":\"Summarize {{row.company}}\"}"],
  "extract": "$.content[0].text",
  "timeout": 60000
}

Error handling

Actions can define onError to map HTTP status codes (or exit codes for exec) to behaviors:

Google Sheets Sidebar

Rowbound includes an Apps Script sidebar that lets you configure actions directly in Google Sheets — no CLI needed. Click a column, edit the action config in a sidebar UI, and save. The sidebar reads and writes the same Developer Metadata config as the CLI, so both stay in sync.

Setup

1. Open your Google Sheet → Extensions → Apps Script
2. Replace the contents of Code.gs with apps-script/Code.gs
3. Click + next to Files → HTML → name it Sidebar → paste apps-script/Sidebar.html
4. In the left panel, click + next to Services → select Google Sheets API → set Identifier to Sheets → click Add
5. Press Cmd+S (or Ctrl+S) to save
6. Reload your spreadsheet — a Rowbound menu appears in the menu bar

Usage

• Rowbound → Actions — view all configured actions, reorder them, or create new ones
• Rowbound → Sources — view and manage data sources (http, exec, webhook, script) with type-specific editors
• Rowbound → Scripts — view, create, edit, and delete reusable scripts with runtime and code editor
• Rowbound → Settings — edit pipeline settings (concurrency, rate limit, retries, backoff)
• Click any action or source to edit its full config
• The column dropdown (●/○ indicators) lets you navigate between columns and see which ones have actions

Supported types

All action types are configurable through the sidebar: HTTP, Waterfall, Formula, Exec, Lookup, Write, and Script. All source types are also supported: HTTP, Exec, Webhook, and Script — including column mapping, dedup, schedule, and update-existing settings.

Note: The sidebar is a config editor only — it doesn't execute the pipeline. Use rowbound run via the CLI to execute. The exec action type can be configured in the sidebar but only executes via the CLI (no shell access in Apps Script).

Multi-sheet use

To use the sidebar across multiple sheets, repeat the setup steps for each sheet. Alternatively, you can set up a test deployment:

1. In the Apps Script editor → Deploy → Test deployments
2. Click the gear icon → select Editor Add-on
3. Click Create new test → select any sheet as test document → Save test
4. The add-on will be available in your test document; for other sheets, repeat the paste-in setup

Development

npm install
npm run dev -- <command>

Security

• Expression sandbox — when conditions and formula expressions run in Node.js vm.runInContext with keyword blocking; convenience sandbox, not a security boundary
• Exec actions — shell commands run locally; template values are shell-escaped but use only with trusted data
• SSRF protection — HTTP requests enforce HTTPS by default and block private/internal IP ranges; set ROWBOUND_ALLOW_HTTP=true for local dev
• Webhook auth — set ROWBOUND_WEBHOOK_TOKEN to require bearer token authentication; server binds to localhost by default
• API keys — stored in ~/.config/rowbound/.env with 600 permissions; .gitignore excludes .env
• Env filtering — only ROWBOUND_*, NODE_ENV, PATH, and explicitly referenced vars are exposed to actions
• MCP permissions — the MCP server inherits the authenticated gws CLI session permissions

License

MIT