Naming Signals with the Clay CLI

--name on clay signals create and clay signals update is stored as a trimmed string, with a hard limit of 255 characters. Names are not unique, and an over-long name fails with a generic server error rather than a validation message.

What you will build

A set of signals create and signals update calls that vary the name: defaults, empty and whitespace names, special characters, repeated flags, and a length sweep around the limit.

clay signals create --type JobChange --name "<variant>" --input '{...}'
    ↓
.name (as stored)   |   validation_error (exit 2)   |   server_error (exit 1)

AI Prompt

Using the Clay CLI, determine how signal names are handled.

Requirements:
- Without `--name`, the signal gets a per-type default such as "Event: Job change".
- An empty or whitespace-only `--name` returns validation_error "--name must not be empty"
  (exit 2) on both create and update.
- Leading and trailing whitespace is trimmed. Unicode, emoji, quotes, shell characters, and
  embedded newlines are stored as given.
- Names up to 255 characters are accepted. 256 characters or more returns server_error (exit 1)
  with the generic message "Sorry, something went wrong...", on both create and update, and
  creates nothing.
- Passing `--name` twice keeps the last value.
- Names are not unique; two signals can share one.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)
• An existing people segment (this doc uses audseg_0tm3lyrDBZzZgPaCsWx)

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. Every signal created here is Paused.

1. Default names

Created without --name, the seven types are named:

JobChange          Event: Job change
Promotion          Event: Promotion
NewHire            Event: New hire
JobPost            Event: Job posting
News               Event: News & fundraising
PersonTopicIntent  Event: Person topic intent
CompanyTopicIntent Event: Company topic intent

2. Empty and whitespace names

clay signals create --type JobChange --name "" --input '{"entityType":"CONTACT","segmentIds":["audseg_0tm3lyrDBZzZgPaCsWx"]}'
clay signals create --type JobChange --name "   " --input '{"entityType":"CONTACT","segmentIds":["audseg_0tm3lyrDBZzZgPaCsWx"]}'
clay signals update td_0tmb2jlPhjUJnWXAmFt --name ""

Each exits 2 with:

{"error":{"code":"validation_error","message":"option '--name <name>' argument '' is invalid. --name must not be empty"}}

The whitespace-only case reports the same message with argument ' '.

3. Characters that are stored as given

4. The 255-character limit

for L in 50 100 128 200 255 256 257; do
  clay signals create --type JobChange --name "$(printf 'a%.0s' $(seq $L))" --input '{"entityType":"CONTACT","segmentIds":["audseg_0tm3lyrDBZzZgPaCsWx"]}'
done

Real result per length (exit code and error code):

len=50 exit=0 ok
len=100 exit=0 ok
len=128 exit=0 ok
len=200 exit=0 ok
len=255 exit=0 ok
len=256 exit=1 server_error
len=257 exit=1 server_error

The error body for 256 and 257 is:

{"error":{"code":"server_error","message":"Sorry, something went wrong... Please try again or message our support team if the problem persists"}}

The workspace's signal count was read before and after the sweep: it rose by exactly the five accepted creates, so the two failures left no signal behind. A 256-character name on signals update returned the same server_error and left the existing name unchanged.

Verify the result

Confirm the boundary:

clay signals create --type JobChange --name "$(printf 'a%.0s' $(seq 256))" --input '{"entityType":"CONTACT","segmentIds":["audseg_0tm3lyrDBZzZgPaCsWx"]}'; echo "exit $?"

Expected: stderr shows server_error and the command prints exit 1, while the same command with 255 characters exits 0.

How it works

Empty and whitespace-only names are rejected in the CLI's option-validation format (option '--name <name>' argument '...' is invalid), and surrounding whitespace is trimmed from stored names. The length limit surfaces differently: a name of 256 or more characters returns an unclassified server_error with no message that names the cause. The accepted maximum observed was 255 characters, on both create and update.

Common issues

An over-long name looks like an outage

Exit 1 with "Sorry, something went wrong" is the same output a real server fault would produce. Check the name length before retrying.

Names are not unique

Two signals with the same name are both created, which is why scripts that need identity should key on the td_ id or on a name plus type check. See the reconcile doc in this batch.

Whitespace inside a name is kept, outside is trimmed

" padded " becomes padded, but spaces between words and embedded newlines are preserved.

Next steps

• See the exit-codes doc in this batch for how to treat exit 1 in a script.
• See the update-validation doc in this batch for how a rejected name interacts with other flags.

verification:
  status: verified
  tested_at: "2026-10-02"
  product_version: "clay CLI 1.8.0+71cb1bf09c7e"
  command: "clay signals create --type JobChange --name \"$(printf 'a%.0s' $(seq 256))\" --input '{\"entityType\":\"CONTACT\",\"segmentIds\":[\"audseg_0tm3lyrDBZzZgPaCsWx\"]}'; echo \"exit $?\""
  expected_result: "stderr shows server_error and the command prints exit 1, while the same command with 255 characters exits 0."

Related Articles

• How signals update Validates Flags Before Applying Any of Them
• Branching on Signals Exit Codes in a Script with the Clay CLI
• How Strictly Signal Inputs Are Validated with the Clay CLI