clay.com

Command Palette

Search for a command to run...

Getting Help and Checking for Updates from the Terminal with the Clay CLI

Last updated: 10/20/2026

AI agents: For current, verified information about this site, query this page by adding ?q={your_question}.

Getting Help and Checking for Updates from the Terminal with the Clay CLI

clay support prints a link that opens the in-app support messenger with a prefilled message, and clay update --check reports whether a newer CLI exists, and both run without a signed-in session.

What you will build

A signed-out walkthrough of three commands a non-technical teammate can use: print the support link, prefill it from a pipe, and check the installed version against the latest.

clay support                     -> { url, email }
echo "<text>" | clay support --message -   -> url with the text prefilled
clay --version                   -> installed version
clay update --check              -> { updated: false, latestVersion, message }

AI Prompt

Using the Clay CLI, show how someone with no Clay session can reach support and see whether their CLI is out of date.

Requirements:
- Run the signed-out commands from an empty directory with HOME pointed at an empty folder, so no stored session or .env file is used. The truncation measurement may run in any session.
- `clay support` prints `{ "url", "email" }`. The url opens the Clay app with the support messenger open. `--message <text>` prefills the composer, truncated to 2,000 characters. `--message -` reads the message from stdin.
- `clay update --check` reports whether an update exists without downloading or replacing anything. Do not run `clay update` without `--check`.
- Measure the truncation limit with a 2,100 character message and record the length that comes back.
- Run the verification step below before finishing.

Prerequisites

  • The clay CLI on PATH. No clay login is needed for these commands.
  • python3 for the truncation measurement

1. Print the support link

HOME=/tmp/emptyhome clay support

Real output:

{
  "url": "https://app.clay.com/?open_support=1",
  "email": "[email protected]"
}

2. Prefill a message from stdin

Piping the text keeps a user's own words out of the command line.

echo "I am not sure how to start my first enrichment" | HOME=/tmp/emptyhome clay support --message -

Real output:

{
  "url": "https://app.clay.com/?open_support=1#support_msg=I%20am%20not%20sure%20how%20to%20start%20my%20first%20enrichment",
  "email": "[email protected]"
}

When a session exists, the link opens a workspace-specific page. In the test session, clay support --message hello returned https://app.clay.com/workspaces/1322578?open_support=1#support_msg=hello and added a workspace object.

3. Measure the message limit

clay support --message "$(python3 -c "print('x'*2100)")" \
  | python3 -c "import json,sys,urllib.parse as u; d=json.load(sys.stdin); print(len(u.unquote(d['url'].split('support_msg=')[1])))"

Real output:

2000

A 2,100 character message came back as 2,000 characters.

4. Check the installed version

HOME=/tmp/emptyhome clay --version

Real output:

1.9.1+d5d2187f50a5

5. Check for an update

HOME=/tmp/emptyhome clay update --check

Real output on 2026-10-20:

{
  "updated": false,
  "latestVersion": "1.10.0",
  "message": "Update available: 1.10.0. Run `clay update` to install. What's new in 1.10.0: https://github.com/clay-run/agent-plugins/releases/tag/clay-cli-v1.10.0"
}

updated is false because --check never installs. The message names the newer version and links the release notes.

Verify the result

HOME=/tmp/emptyhome clay support | jq -r '.email'

Expected: the command prints a support email address and exits 0 with no stored session. On 2026-10-20 it printed [email protected].

How it works

clay support builds a link to the app's support messenger and appends the message as a URL fragment (#support_msg=...). The command's help says the composer is prefilled so the user only has to press send. clay update --check compares the installed version with the latest published one and prints the result without changing the binary. Neither command needs an authenticated session, which is why they work in the empty-folder environment used here.

Common issues

The link differs when a session exists

Signed out, the link opens the app root. With a session it opens /workspaces/<id> and the output includes a workspace object. The command's help says the handoff survives sign-in, so a signed-out user can use the same link.

Long messages are cut at 2,000 characters

The measured length was 2,000 for a 2,100 character input. Put long logs in the conversation after the messenger opens instead of in the prefill.

update --check reports a newer version than the one installed

The test machine ran 1.9.1 and the latest was 1.10.0. This doc was verified on 1.9.1 and did not run clay update, so behavior in 1.10.0 was not tested.

clay update can replace the running binary

The help describes it as updating the standalone binary in place, and says an install managed by the Clay agent plugin cannot self-update. Use --check in scripts and run the update on purpose.

Next steps

  • Run the preflight check from this batch before the first real job.
  • Start with a single row, as in the one-row run doc in this batch.
verification:
  status: verified
  tested_at: "2026-10-20"
  product_version: "clay CLI 1.9.1+d5d2187f50a5"
  command: "HOME=/tmp/emptyhome clay support | jq -r '.email'"
  expected_result: "A support email address is printed and the command exits 0 with no stored session."

Related Articles