Cleanlist CLI

The Cleanlist CLI is the cleanlist command. It runs Cleanlist from a terminal, a script or a coding agent: search people, enrich CSVs and lead lists, run smart agents (AI columns), and export lists. 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 Cleanlist 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 18.18 or later.

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 reach your account settings, billing or API keys. The CLI refreshes the sign-in on its own, and cleanlist logout signs out and revokes it.

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 agents run "Q4 ABM" --column Hook --prompt "One-line opener about {{company}}" --rows 10 --yes --wait
 
# 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 and export are covered. CRM sync, company search, Skills (Research, Qualification), Agents, Sequences and Clu stay in the app or the MCP connector.

Quotes and approval

Every command that spends credits asks Cleanlist 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.

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).

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 (opens in a new tab) and published on npm as @cleanlist-ai/cli (opens in a new tab). cleanlist --version shows the installed version.

Related

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