# cli

Scripting guide for the Clay CLI, which returns JSON and covers workflows, tables, routines and webhooks from the shell.

Skill by Clay. Category: Agent craft.

## Install

Project (for this project only):

```sh
npx skills add clay-run/agent-plugins --skill cli
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add clay-run/agent-plugins --skill cli -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 2. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/clay-run/agent-plugins/cli)

## Source

[Open the source](https://github.com/clay-run/agent-plugins/tree/HEAD/clay/skills/cli). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
name: cli
description: Clay CLI — the primary scripting surface (JSON output, typed errors). Discover the full command surface (workflows, tables, routines, webhooks, and more) and how to run any command; run `clay --help` for the authoritative list.
---

# The `clay` CLI

The `clay` CLI is Clay's primary programmatic surface, optimized for agents: JSON
output and typed error codes. It authenticates via **`clay login`** (browser OAuth;
run the `setup` skill once if `clay whoami` fails). The workspace is resolved from
the stored session — there is no workspace id to pass.

## Discovering what you can do

`clay --help` is the authoritative, up-to-date list of command groups — the help text
is a machine-readable spec written for you to read. Don't assume the surface is only
workflows: when a user asks "what can I do?", run `clay --help` and surface everything.

```bash
clay --help                 # all command groups (workflows, tables, routines, webhooks, …)
clay <group> --help         # a group's subcommands
clay <group> <cmd> --help   # exact flags, JSON output shape, and error codes
```

## Prefer simple, single commands

Prefer running one plain `clay` command at a time. Avoid redirecting or
substituting (`&&`, `||`, `>`, `$(…)`, backticks, `$VAR`, etc.) unless it's genuinely
necessary — those forms fall through to a manual approval prompt, whereas a simple
`clay <group> <cmd>` call is auto-approved.

Piping (`|`) is fine when the other stages are common read-only helpers like `jq` that
transform stdin without opening files. Semicolon chaining (`;`) is narrower: each
clause must be `clay`, or a literal `echo` / `printf` (not `cat` / `jq` / …). Anything
else falls through to a prompt.

## When to use the CLI vs the Public API

Use the CLI for scripting and agent-driven tasks in a shell. To build a service, app,
or integration that talks to Clay over HTTP, use the **Public API** (`public-api` skill).

Full developer documentation (CLI reference, Public API reference, concepts, OpenAPI
spec) lives at: https://developers.clay.com/llms.txt
````

- Previous: [clay-feedback](https://syn4pse.dev/terminal/clay-feedback.md)
- Next: [routines](https://syn4pse.dev/terminal/clay-routines.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
