leadgrow-clay-cli

CLI + MCP server for Clay.com — pull table schemas, create tables from templates, modify templates, diff schemas, and scan workspaces. Built for both human operators and AI agents.

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
• MCP Server exposes all commands as tools for Claude, Cursor, and other AI agents
• Agent-friendly: --json and --quiet flags suppress progress output

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

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

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 |

MCP Server

The CLI includes an MCP (Model Context Protocol) server that exposes all commands as tools for AI agents.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "clay": {
      "command": "node",
      "args": ["/path/to/leadgrow-clay-cli/dist/mcp.js"],
      "env": {
        "CLAY_SESSION_COOKIE": "your-session-cookie"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "clay": {
      "command": "node",
      "args": ["/path/to/leadgrow-clay-cli/dist/mcp.js"],
      "env": {
        "CLAY_SESSION_COOKIE": "your-session-cookie"
      }
    }
  }
}

Available MCP Tools

| Tool | Description | |------|-------------| | clay_pull | Extract table schema as template JSON | | clay_create | Create table from template with field ID remapping | | clay_modify | Add, remove, rename columns in a template | | clay_list | List tables in workspace (discover table IDs) | | clay_diff | Compare two templates | | clay_get_table | Get raw table data from Clay API | | clay_config | Show, set, or clear CLI configuration |

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.

Environment Variables

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

License

MIT