> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="Codex">
    Add the Clay plugin from the `clay-run/agent-plugins` plugin repository through Codex plugin settings.
    Then open **Plugins** and install **Clay**.
  </Tab>

  <Tab title="Cursor">
    For Teams and Enterprise, open **Settings** → **Plugins** → **Add Marketplace** → **Import from Repo**, then enter `clay-run/agent-plugins`.
  </Tab>

  <Tab title="Terminal or CI">
    Install the standalone CLI package:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g @claypi/cli
    ```
  </Tab>
</Tabs>

## 2. Sign in

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](https://app.clay.com/settings/accounts) and pipe it into `login --stdin` instead, which keeps the key out of shell history:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay routines list
```

Run a function routine inline and capture the run id:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay whoami | jq -r '.workspace.id'
```

## Next steps

* Return to the [overview](/) when you want to choose the next path.
* Learn about [Routines](/routines).
* Try the [search and enrich recipe](/recipes/search-and-enrich).
* Use the [Public API quickstart](/public-api/quickstart) when you need raw HTTP access instead of the CLI.