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.
Use workspace context internally
Once the CLI knows which workspace a credential is for, every successful command's JSON
carries a workspace: { id, name } key naming the workspace it authenticated as. Use this
information internally. Only mention authentication, the user, or the workspace when the
user asks or an actual account/workspace issue needs their attention. Running the first
command, receiving identity in a result, or loading this skill later in a conversation
does not call for an identity announcement. This applies to managed and standalone CLI
sessions. Don't ask the user for workspace information merely because the key is absent — it is
absent when a command never had to resolve the workspace, and when its result is a top-level
JSON array with nowhere to put it.
A browser sign-in covers every workspace the user selects on the consent screen, and leaves
the first one selected active; clay login --device covers one workspace per run. Either way
the workspaces already signed in are kept, so clay login again adds more rather than
replacing them. clay workspaces list shows the ids and clay workspaces switch <id> moves
between them, so switch explicitly to work in one the sign-in did not leave active. When a
payload carries no workspace key and you need to know, clay workspaces current answers
directly. Inside a managed Clay session none of this applies: the session runs in the one
workspace it was created in, and clay login / clay logout / clay workspaces are
unavailable there. Never ask the user to sign in — but if they ask to work in a different
workspace, tell them to switch workspaces in Clay and start a new chat there, since this
session cannot move.
Discovering commands
When a user asks what they can do with Clay, use the clay skill when it is available — that is the table of
contents for product surfaces. This skill is how to invoke the CLI.
clay --help is the live list of top-level commands. The help text is a machine-readable
spec: use it for command names, flags, JSON output shape, and error codes. Do not treat
it as the answer to "what can I do with Clay?"
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
