CluGTM CLI

The CluGTM CLI is the cleanlist command. It runs CluGTM from a terminal, a script or a coding agent: search people, enrich CSVs and lead lists, run smart agents (AI columns), export lists, manage GTM agents, call Clu’s own tools as actions, and subscribe webhooks. It calls the v2 REST API, so it uses the same data, lists, credit balance and prices as the app.

It is built for coding agents such as Claude Code, Cursor and Codex:

• Data stays in files. -o and --format csv move rows between files and CluGTM without pasting them into the conversation.
• Machine-readable output. Tables in a terminal, JSON when piped, and fixed exit codes an agent can branch on.
• No surprise prompts. Without a terminal, the CLI never waits for input. A paid command stops with exit code 7 and prints the quote, so the agent asks you first.
• Small context. The agent reads a short skill file and --help when it needs it, instead of loading a full tool list.

Install

The CLI needs Node.js 22.23.4 or later on Node 22, 24.22.1 or later on Node 24, or 26.12.1 or later. Those are the releases patched for CVE-2026-111497.

npx @cleanlist-ai/cli --help        # run without installing
npm install -g @cleanlist-ai/cli    # or install the cleanlist command

The rest of this page writes cleanlist. With npx, use npx @cleanlist-ai/cli in its place.

Sign in

Browser and device sign-in give the CLI access to the public API only, for the workspace you picked. It can’t change account settings or billing, and it can’t create or revoke API keys. The CLI refreshes the sign-in on its own, and cleanlist logout signs out and revokes it: a revoked or replaced sign-in stops working within a minute.

A browser or device sign-in never holds the opt-in scopes for deleting lists and leads, sending, or writing to your CRM. For those, sign in with an API key that has them ticked under Settings → API keys → Permissions.

Credentials are stored in your system keychain (macOS Keychain, or libsecret on Linux), or in ~/.config/cleanlist/credentials.json (readable only by you) when there is no keychain.

Workspaces

Each sign-in is a profile tied to one workspace. cleanlist whoami shows the workspace, user and plan you are acting as.

cleanlist login --profile acme     # add a second workspace
cleanlist profiles                 # list saved profiles
cleanlist credits --profile acme   # use it for one command (or set CLEANLIST_PROFILE=acme)

Set up your coding agent

Run one of these in your project so the agent knows the CLI and its rules:

cleanlist skill --target claude    # Claude Code: .claude/skills/cleanlist/SKILL.md
cleanlist skill --target cursor    # Cursor: .cursor/rules/cleanlist.mdc
cleanlist skill --target agents    # Codex and other tools: appends a section to AGENTS.md

cleanlist skill without --target prints the instructions. They tell the agent to:

• check sign-in with cleanlist whoami;
• use the main workflows below;
• show you every quote, including any CRM note, and only re-run with --yes after you approve;
• write rows to files instead of printing them into the chat;
• branch on exit codes.

Then ask in plain language, for example: “Enrich leads.csv with work emails and save the result next to it. Show me the cost first.”

What you can do

# Enrich a CSV and write the enriched file
cleanlist enrich csv leads.csv --dry-run                 # cost only
cleanlist enrich csv leads.csv --yes -o leads.enriched.csv
 
# Find people at a set of companies (one domain per line), then save them
cleanlist people search --company-domains-file domains.txt --title "VP Sales" --json
cleanlist lists add "Q4 ABM" --from-task <task_id>
 
# Read and export lists
cleanlist lists
cleanlist lists rows "Q4 ABM" --all --format csv > q4.csv
cleanlist lists export "Q4 ABM" -o q4.csv
 
# Enrich a list, or one person
cleanlist enrich list "Q4 ABM" --scope full --yes --wait
cleanlist enrich person --linkedin https://www.linkedin.com/in/... --yes
 
# Fill an AI column on the first 10 rows
cleanlist smart-agents run "Q4 ABM" --column Hook --prompt "One-line opener about {{company}}" --rows 10 --yes --wait
 
# GTM agents: list them, read a run's records, turn one off
cleanlist agents list
cleanlist agents runs <agent_id>
cleanlist plays results <run_id> --wait
cleanlist agents off <agent_id>
 
# Anything Clu can do: list the actions, run one
cleanlist actions list
cleanlist actions run agents.get --args '{"agent_id":"..."}' --json
 
# Get events at your own URL (the signing secret is shown once)
cleanlist webhooks add https://example.com/hooks/cleanlist --events play_run.completed,reply.received
 
# Account
cleanlist credits
cleanlist usage --group-by tool

Lists can be named by id or by exact name. cleanlist --help lists every command, and cleanlist <command> --help shows its flags and examples.

People search, lists, enrichment, smart agents, GTM agents, actions, webhooks and export are covered. CRM sync, company search, the Research and Qualification skills and Clu stay in the app or the MCP connector.

Quotes and approval

Every command that spends credits asks CluGTM for a quote first (POST /api/v2/credits/estimate), then:

If your workspace pushes enriched people to HubSpot or Salesforce automatically, the quote includes a CRM note saying so. A quote lasts 5 minutes and works once.

actions run works the same way with a card instead of a quote. An action that spends, sends, deletes or writes to a CRM returns a card and runs nothing. --yes, or a yes at the prompt, confirms it; without a terminal it exits 7 with the card, and cleanlist actions confirm <card_id> --session <session_id> runs it once the person approves. --max-credits caps it. Sends, CRM writes and deletes also need the key’s opt-in scope (sequences:write, crm:write, lists:delete); without it they exit 3 with opt_in_scope_required. Turning an agent on, running it now and changing its limits exit 3 with person_required: a person does those in the app.

enrich csv imports the file into a list before it quotes, and the import is free. If you stop at the quote, re-running the same command reuses that list and doesn’t import the rows twice.

Output and exit codes

Output is a table in a terminal and JSON when piped. Choose with --json or --format table|json|jsonl|csv. Data goes to standard output and progress messages to standard error (-q hides them). Errors are JSON on standard error when piped, with a fix hint.

Exit codes

--wait checks progress with a growing delay and follows the API’s retry hints. --timeout 10m sets how long to wait (30 minutes by default).

Only a GET is retried, up to 3 tries, on a 502, 503 or 504 or when no response comes back. A POST, PATCH or DELETE is sent once and never resent, so a write can’t run twice; when one gets no response, check before running it again.

Limits

The CLI shares the API’s rate limits: 60 requests a minute per workspace and 30 per API key. API keys can run 60 people searches a day, so avoid paging every result with people search --all in loops.

Environment variables

Troubleshooting

Still stuck? Email support@cleanlist.ai with the command you ran and the error.

Source and releases

The CLI is open source (MIT) at github.com/Cleanlist-ai/cleanlist-cli  and published on npm as @cleanlist-ai/cli. cleanlist --version shows the installed version.

Related

• Connect CluGTM to Claude (MCP)
• API reference (v2)
• Authentication and API keys
• Credits and quotes
• SDKs
• Pricing and credits