> ## 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, configure your API key, 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 API key setup 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. Set your API key

The plugin, MCP server, and CLI all authenticate with a Clay API key. Create one in [Account settings](https://app.clay.com/settings/accounts).

Export the key in the shell or environment your agent uses:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CLAY_API_KEY="your_api_key"
```

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