Installing and Verifying the Clay CLI with the Clay CLI

The Clay CLI installs with one script from the clay-run/agent-plugins repository, and clay whoami confirms which user and workspace the installed binary is signed into. An existing sign-in carries over when the CLI is updated.

What you will build

A two-command check that the CLI is installed at the expected version and authenticated against the intended workspace.

install-cli.sh --version <version> --method native
    ↓
clay --version
    ↓
clay whoami   (user and workspace the CLI is signed into)

AI Prompt

Using the Clay CLI, install or update the CLI and confirm it is authenticated.

Requirements:
- Clone https://github.com/clay-run/agent-plugins and read `clay/cli-min-version` for the pinned version.
- Run `bash clay/scripts/install-cli.sh --version <pinned-version> --method native`, then add `$HOME/.local/bin` to PATH.
- Passing `--method native` avoids an ambiguity when another executable named `clay` is already on PATH.
- The installer reports the version it actually installed, which can be newer than the pinned minimum.
- `clay whoami` prints `{ workspace: { id, name }, user: { id, name, email } }`. An existing OAuth session in `~/.config/clay` is reused after an update.
- Run the verification step below before finishing.

Prerequisites

• git and bash
• A Clay account. Signing in the first time uses clay login; this example starts from a machine that is already signed in.

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Read the pinned version

git clone https://github.com/clay-run/agent-plugins.git clay-agent-plugins
cat clay-agent-plugins/clay/cli-min-version

Real output on 2026-10-09:

1.9.0

2. Run the installer

bash clay-agent-plugins/clay/scripts/install-cli.sh --version 1.9.0 --method native
export PATH="$HOME/.local/bin:$PATH"

Real output, trimmed to the summary lines:

{
  "updated": true,
  "latestVersion": "1.9.1",
  "message": "Updated to 1.9.1 from 1.8.0. What's new in 1.9.1: https://github.com/clay-run/agent-plugins/releases/tag/clay-cli-v1.9.1"
}

Installed Clay 1.9.1+d5d2187f50a5 at /Users/<user>/.local/bin/clay

The pinned minimum was 1.9.0; the installer moved the binary from 1.8.0 to the latest release, 1.9.1.

3. Confirm the version and the sign-in

clay --version
clay whoami

Real output:

1.9.1+d5d2187f50a5

{
  "workspace": { "id": "<workspace id>", "name": "Example Workspace" },
  "user": { "id": "<user id>", "name": "<name>", "email": "<email>" }
}

The sign-in from the previous version was still valid after the update, so no second clay login was needed.

Verify the result

clay --version && clay whoami | jq -r '.workspace.name'

Expected: the CLI prints a version at or above the pinned minimum, followed by the workspace name.

How it works

The installer places the clay binary in $HOME/.local/bin. Authentication is stored separately under ~/.config/clay, so replacing the binary does not remove the session. clay whoami reads that stored session and reports the workspace it applies to.

Common issues

Another clay executable is earlier on PATH

which -a clay lists every clay on PATH. On the machine used here it listed two: $HOME/.local/bin/clay and a second one under $HOME/.local/node/bin/clay. Putting $HOME/.local/bin first in PATH, and running hash -r in the current shell, selects the intended one.

The installer installs a newer version than the pinned one

--version was 1.9.0 in this run and the installer reported latestVersion 1.9.1, which is the version that ended up installed. Check clay --version after installing instead of assuming the pinned number.

The CLI is not signed in

clay login signs in through the browser, and clay login --device prints a link and code for machines without a browser. That flow needs a person to approve it, so it is described here from the command help and was not executed for this example.

Next steps

• Reading the Onboarding Starter Tasks with the Clay CLI
• Creating an API Key and Making a First REST Call with the Clay CLI

verification:
  status: verified
  tested_at: "2026-10-09"
  product_version: "clay CLI 1.9.1"
  command: "clay --version && clay whoami | jq -r '.workspace.name'"
  expected_result: "The CLI prints a version at or above the pinned minimum, followed by the workspace name."