leadgrow-clay-cli

CLI for Clay.com — pull table schemas, create tables from templates, modify columns, diff schemas, export records, browse presets, apply recipes, and push leads via webhooks. Built for humans and AI agents alike.

CLI-first philosophy: Every command outputs clean JSON to stdout and progress to stderr. AI agents like Claude Code, Cursor, or any tool with terminal access should just call clay commands directly via the shell — no MCP server needed. The CLI is the agent interface.

Features

• Pull table schemas as portable JSON templates
• Create new tables from templates with automatic field ID remapping
• Modify templates: add, remove, rename columns
• Diff two templates to see what changed
• List tables across workspaces and folders
• Presets browse and search all workspace presets (recipes, actions, waterfalls, claygents)
• Recipe apply column group templates to tables
• Records export records from tables with batched fetching
• Push leads to Clay webhooks from JSON or CSV files
• AI-native: --json and --quiet flags for clean machine-readable output — just run CLI commands from any AI agent

Installation

npm install -g leadgrow-clay-cli

Or clone and build locally:

git clone https://github.com/LeadGrowGTM/leadgrow-clay-cli.git
cd leadgrow-clay-cli
npm install
npm run build

Quick Start

# 1. Run the interactive setup wizard
clay setup

# Or authenticate non-interactively
clay login --email [email protected] --password yourpassword

# 2. Pull a table schema
clay pull --table t_abc123 --output template.json

# 3. Modify the template
clay modify --template template.json \
  --remove "Created At" \
  --rename "Old Name:New Name" \
  --add-text "Custom Field" \
  --output modified.json

# 4. Create a new table from the template
clay create --template modified.json --workbook wb_xyz789

# 5. Diff two templates
clay diff template.json modified.json

# 6. Browse workspace presets
clay presets "find email" --type recipe

# 7. Export records from a table
clay records --table t_abc123 --view v_def456 --output records.json

# 8. Push leads to a webhook
clay push --webhook https://hooks.clay.com/v1/webhook/wh_abc --file leads.csv

Commands

clay setup

Interactive setup wizard with ASCII art banner. Walks you through authentication (email/password or session cookie), workspace detection, and config verification.

clay setup

Supports two auth methods:

1. Email & password — authenticates via Clay API, extracts session automatically
2. Session cookie — paste your claysession cookie from browser DevTools

clay login

Non-interactive authentication. Use clay setup for first-time setup.

clay login --email <email> --password <password>

clay pull

Extract a table schema as a template JSON.

clay pull --table <tableId> [--output <file>] [--raw]

| Flag | Description | |------|-------------| | -t, --table | Source table ID (e.g. t_abc123) | | -o, --output | Save to file (default: stdout) | | --raw | Include full typeSettings |

clay create

Create a new table from a template. Handles field ID remapping and dependency ordering.

clay create --template <file> --workbook <wbId> [--name <name>] [--delay <ms>] [--dry]

| Flag | Description | |------|-------------| | --template | Template JSON file | | -b, --workbook | Target workbook ID | | -n, --name | Override table name | | --delay | Delay between column creates in ms (default: 200) | | --dry | Show plan without creating |

clay modify

Modify a template: add, remove, or rename columns.

clay modify --template <file> [--remove <name>]... [--rename <from:to>]... [--add-text <name>]...

| Flag | Description | |------|-------------| | --template | Template JSON file | | -o, --output | Save result (default: stdout) | | --remove | Remove column by name (repeatable) | | --rename | Rename column as from:to (repeatable) | | --add-text | Add text input column (repeatable) | | --add-number | Add number input column (repeatable) | | --add-date | Add date column (repeatable) | | --table-name | Set table name |

clay list

List tables in a workspace or folder.

clay list [--folder <folderId>] [--deep]

| Flag | Description | |------|-------------| | -f, --folder | Scan specific folder | | --deep | Full scan with field counts and types |

clay diff

Compare two template JSON files.

clay diff <fileA> <fileB>

clay presets

List and search workspace presets (recipes, actions, waterfalls, claygents).

clay presets                    # List all presets
clay presets "find email"       # Search by name
clay presets --type recipe      # Filter by type

| Flag | Description | |------|-------------| | --type | Filter by type: action, recipe, waterfall, claygent, recent_search |

clay recipe

Apply a recipe preset to a table (adds multiple columns at once).

clay recipe apply <recipeId> --table <tableId> --view <viewId>
clay recipe apply re_abc123 --table t_xyz --view v_def --ingredients '[...]'

| Flag | Description | |------|-------------| | -t, --table | Target table ID | | --view | Target view ID | | --ingredients | Optional JSON column mappings |

clay records

Export records from a Clay table.

clay records --table <tableId> --view <viewId>
clay records --table t_abc --view v_def --output records.json --batch-size 50

| Flag | Description | |------|-------------| | -t, --table | Table ID to export from | | --view | View ID to export from | | --batch-size | Records per API batch (default: 100) | | -o, --output | Save to file (default: stdout) |

clay push

Push leads to a Clay webhook from a JSON or CSV file.

clay push --webhook https://hooks.clay.com/v1/webhook/wh_abc --file leads.json
clay push --webhook https://hooks.clay.com/v1/webhook/wh_abc --file leads.csv

| Flag | Description | |------|-------------| | --webhook | Clay webhook URL | | --file | Path to JSON array or CSV file |

clay config

Manage CLI configuration.

clay config show                          # Display config status
clay config set <key> <value>             # Set a config value
clay config clear                         # Delete config file

Valid keys: session, workspaceId, defaultWorkbook, homeFolderId

Common Flags

| Flag | Description | |------|-------------| | -s, --session | Clay session cookie (or CLAY_SESSION_COOKIE env) | | -w, --workspace | Workspace ID (or CLAY_WORKSPACE_ID env) | | --json | Suppress stderr, output JSON only | | -q, --quiet | Suppress stderr progress output | | -h, --help | Show help | | -v, --version | Show version |

Using with AI Agents

Recommended: CLI-first (Claude Code, Cursor, any AI with shell access)

AI agents should just call clay commands directly. No MCP server needed. Every command outputs clean JSON to stdout, so agents can parse results natively.

# Agent pulls a schema
clay pull --table t_abc123 --json --quiet

# Agent modifies it
clay modify --template schema.json --remove "Facebook Url" --json --quiet

# Agent creates the table
clay create --template modified.json --workbook wb_xyz --json --quiet

# Agent exports records
clay records --table t_abc123 --view v_def456 --json --quiet

# Agent searches presets
clay presets "email waterfall" --type recipe --json --quiet

# Agent pushes leads to a webhook
clay push --webhook https://hooks.clay.com/v1/webhook/wh_abc --file leads.csv --json --quiet

The --json flag ensures only JSON goes to stdout (no progress noise). The --quiet flag suppresses stderr progress. Use both for cleanest agent output.

Optional: MCP Server (only if no shell access)

An MCP server is included for environments where the AI has no terminal access (e.g. Claude Desktop app). If your agent can run shell commands, use the CLI directly instead.

{
  "mcpServers": {
    "clay": {
      "command": "clay",
      "args": ["mcp"],
      "env": {
        "CLAY_SESSION_COOKIE": "your-session-cookie"
      }
    }
  }
}

Template Format

Templates are portable JSON representations of Clay table schemas:

{
  "tableId": "t_abc123",
  "tableName": "My Table",
  "columnCount": 15,
  "fieldIdToName": {
    "f_abc": "Company",
    "f_xyz": "Email"
  },
  "columns": [
    {
      "id": "f_abc",
      "name": "Company",
      "type": "text",
      "dataType": "text",
      "originalIndex": 0,
      "isEnrichment": false
    },
    {
      "id": "f_xyz",
      "name": "Find Email",
      "type": "action",
      "dataType": "json",
      "actionKey": "leadmagic-find-work-email",
      "actionPackageId": "...",
      "actionInputs": [...],
      "isEnrichment": true,
      "inputFieldIds": ["f_abc"],
      "originalIndex": 1
    }
  ]
}

The fieldIdToName map enables field ID remapping when creating tables from templates — references like {{f_abc}} in formulas get remapped to the new table's field IDs.

Development

npm install          # Install dependencies
npm run build        # Build with tsup (outputs dist/index.js + dist/mcp.js)
npm run lint         # Type check (tsc --noEmit)
npm test             # Run all tests (32 tests across 5 files)
npm run test:watch   # Watch mode
npm run dev          # Run CLI via tsx (no build needed)

Tests use Vitest with mocked fetch — no live API calls required.

Environment Variables

| Variable | Description | |----------|-------------| | CLAY_SESSION_COOKIE | Clay session cookie (alternative to clay login) | | CLAY_WORKSPACE_ID | Default workspace ID |

License

MIT