Clay plugin quickstart

Install the Clay plugin or CLI, sign in, and run your first command.

The Clay plugin is the fastest way to use Clay from Claude Code, Codex, or Cursor. It gives agents both Clay’s MCP server and the Clay CLI.

The CLI (clay) is JSON-first, so agents and scripts can inspect results without parsing prose.

1. Install the plugin or CLI

Install the plugin for your agent environment. If you only need the CLI in a terminal, local script, or CI job, install the standalone package instead.

Claude Code

Install the Clay plugin from the clay-run/agent-plugins plugin repository using your workspace’s Claude Code plugin setup flow. Then continue with sign-in below.

Codex

Add the Clay plugin from the clay-run/agent-plugins plugin repository through Codex plugin settings. Then open Plugins and install Clay.

Cursor

For Teams and Enterprise, open Settings → Plugins → Add Marketplace → Import from Repo, then enter clay-run/agent-plugins.

Terminal or CI

Install the standalone CLI package:

npm install -g @claypi/cli

2. Sign in

The plugin, MCP server, and CLI all authenticate with the same session. Sign in once:

clay login

This opens a browser to authorize the CLI and stores the session locally; the Clay MCP server uses that same session. If you’re in a headless or CI environment where a browser sign-in isn’t possible, create an API key in Account settings and pipe it into login --stdin instead, which keeps the key out of shell history:

echo "$CLAY_API_KEY" | clay login --stdin

If your agent already had the plugin installed before you signed in, its MCP server was spawned with the old (missing) session and won’t pick up the new one on its own — restart the agent (fully quit and reopen it) after signing in.

3. Verify access

Confirm the CLI can see your user and workspace:

clay whoami

The workspace is resolved from your session or API key. You do not need to set a workspace id.

4. Run a routine

List routines available to your workspace:

clay routines list

Run a function routine inline and capture the run id:

echo '{"items":[{"id":"row-1","inputs":{"domain":"clay.com"}}]}' \
  | clay routines runs start function:t_abc123 --input - \
  | jq -r '.routineRunId'

Fetch results once the run completes:

clay routines runs get run_xyz789

5. Explore Workflows (Alpha)

Workflows are in Alpha. They can be created, edited, validated, run, inspected, and batch-run from the plugin and CLI.

clay workflows list
clay workflows create --name "My Workflow"

Work with JSON

Successful commands write JSON to stdout. Failures write a structured error to stderr and exit non-zero.

Pipe stdout to jq to extract fields:

clay whoami | jq -r '.workspace.id'

Next steps

• Return to the overview when you want to choose the next path.
• Learn about Routines.
• Try the search and enrich recipe.
• Use the Public API quickstart when you need raw HTTP access instead of the CLI.