clay.com

Command Palette

Search for a command to run...

Patching Campaign Settings with the Clay CLI

Last updated: 9/12/2026

Patching Campaign Settings with the Clay CLI

Update a campaign's name, scheduling settings, or AI context with a strict, partial JSON patch, using Clay's real campaigns update command, which enforces the same per-field edit gates as the Campaigns UI itself.

What you will build

A targeted patch to one or more editable fields on an existing campaign, without needing to resend its full configuration.

clay campaigns update <campaign-id> --input '{...}'
    ↓
only "name", "settings", "claygentContext", or "leadBaseSegmentId" may be set
    ↓
{ id, name, status, settings, claygentContext, ..., updatedAt }

AI Prompt

Using the Clay CLI, patch specific fields on an existing campaign.

Requirements:
- `clay campaigns update <campaign-id> --input <json|file|->` accepts a
  strict, non-empty object containing ONLY "name", "settings",
  "claygentContext", or "leadBaseSegmentId" -- any other key is rejected.
- "leadBaseSegmentId" (attaching/changing the campaign's audience) is only
  editable while the campaign is in draft status.
- "name" is editable in any campaign status. "settings" and
  "claygentContext" fields are validated against the campaign's CURRENT
  status -- the same per-field edit gates the Campaigns UI enforces, so an
  edit that works on a draft campaign can be rejected on an active one.
- Status, provider, budget, "leadExclusionSegmentIds", sequence content,
  variants, deletion, and Claygent skill settings are NOT expressible here --
  use the dedicated commands for those (`campaigns sequence edit`,
  `campaigns update-claygent`, `campaigns variants`).
- Campaign intent (inside claygentContext) uses Clay's lossless campaign
  text grammar, same as sequence copy.
- The response echoes the campaign's full config, same shape as
  `campaigns get`.
- 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)
  • jq

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. Rename a campaign

clay campaigns update cam_0tl84os74M6XWkVnp2s --input '{"name":"TPC CLI Docs Test Campaign (renamed)"}'

2. Attach an audience (draft campaigns only)

clay campaigns update cam_0tl84os74M6XWkVnp2s --input '{"leadBaseSegmentId":"audseg_0tjs3u3yAgacWPpe926"}'

Real output confirms the attachment landed under audience.baseSegment:

{
  "id": "cam_0tl84os74M6XWkVnp2s",
  "audience": { "baseSegment": { "id": "audseg_0tjs3u3yAgacWPpe926" } }
}

3. Patch from a file or stdin

cat > update.json <<'EOF'
{"settings": {"followUpPercentage": 50}}
EOF
clay campaigns update cam_0tl84os74M6XWkVnp2s --input update.json
cat update.json | clay campaigns update cam_0tl84os74M6XWkVnp2s --input -

Verify the result

Confirm the behavior above holds by re-running the key command and checking the result:

clay campaigns update cam_0tl84os74M6XWkVnp2s --input '{"leadBaseSegmentId":"audseg_0tjs3u3yAgacWPpe926"}'

Expected: The campaign's audience.baseSegment.id reflects the attached segment in the response, and the same command rejects any key outside name/settings/claygentContext/leadBaseSegmentId.

How it works

campaigns update is deliberately narrow: it only accepts the handful of top-level fields Clay calls "Sculptor"-editable, and rejects anything else outright, rather than silently ignoring unrecognized keys. This is what makes it safe to build a small patch object programmatically without accidentally touching sequence content, variants, or Claygent skills, which each have their own dedicated command with its own status rules.

Common issues

validation_error patching "leadBaseSegmentId" on a live campaign

Cause: assuming any campaign field is editable at any time.

Fix: leadBaseSegmentId is editable only on a draft campaign, confirmed by the command's own documented rule. Once a campaign is active or beyond, its audience is fixed; create a new campaign to target a different one.

Sending sequence content, variants, or a status change through campaigns update

Cause: expecting one general-purpose "update campaign" command to cover everything.

Fix: those are deliberately separate commands: campaigns sequence edit for message content, campaigns variants for A/B tests, and status changes are not exposed via this command at all.

Next steps

  • Use clay campaigns get <campaign-id> first to read the current config before building a partial patch.
  • For sequence content itself, use clay campaigns sequence edit.
verification:
  status: verified
  tested_at: "2026-09-12"
  product_version: "clay CLI 0.19.0"
  command: "clay campaigns update cam_0tl84os74M6XWkVnp2s --input '{\"leadBaseSegmentId\":\"audseg_0tjs3u3yAgacWPpe926\"}'"
  expected_result: "The campaign's audience.baseSegment.id reflects the attached segment in the response, and the same command rejects any key outside name/settings/claygentContext/leadBaseSegmentId."