CLI

The clarify CLI covers the whole platform from a terminal: sign up, create and manage workspaces, and read and write records. It also runs every Clarify AI tool, including email, calendar, agents, campaigns, and SQL. It is built for people and tuned for agents: output is compact JSON when piped, errors are machine-readable, and one command prints the full reference.

Install

# macOS and Linux
curl -fsSL https://clarify.ai/install.sh | sh

# Windows
irm https://clarify.ai/install.ps1 | iex

You can also install with Homebrew (brew install clarifyhq/tap/clarify-cli) or Scoop. Each release is a single binary for macOS, Linux, and Windows on Intel and ARM.

Sign in

clarify signup --name "Acme Inc"   # new to Clarify
clarify login                      # existing account

Both open your browser and ask you to confirm a code. In CI or anywhere without a browser, use a Personal API key instead:

export CLARIFY_API_KEY=YOUR_API_KEY
export CLARIFY_WORKSPACE=your-workspace

To keep a repo on one workspace, commit a .clarify.json file to it:

{ "workspace": "your-workspace" }

Commands run in that directory or below use it instead of your default workspace. --workspace and CLARIFY_WORKSPACE still take precedence, and clarify whoami shows which pin is in effect.

Work with records

clarify objects get person                       # fields, their shapes, and options
clarify records list person --filter job_title=*VP* -f id,name.full_name
clarify records create person --set name.first_name=Jane --set email_addresses=jane@acme.com
clarify records update deal <id> --set stage=Won --set amount=50000
clarify query "select stage, sum(amount) from deal group by stage"

Path parameters go in order (records get person <id>). --set field=value sets a body field, and the CLI converts the value to the field's type. -d @file.json sends a whole body. records create-many person -d @people.jsonl imports one record per line.

Manage workspaces and people

clarify workspaces list
clarify workspaces create --name "Acme Labs"
clarify workspaces use acme-labs
clarify invitations create --email sam@acme.com
clarify users set-role <user-id> --role admin
clarify api-keys create --name ci

Everything else

clarify tools list shows every Clarify AI tool, and clarify tools <name> --param value runs one:

clarify tools send-email --to jane@acme.com --subject "Follow-up" --body "Thanks for today"
clarify tools get-calendar-events --start 2026-10-01T00:00:00Z --end 2026-10-08T00:00:00Z

clarify api <METHOD> <path> calls any endpoint in the API reference, with the same sign-in. It prints responses exactly as the API sends them, so you can send one back unchanged; add -o json to flatten them like other commands.

For agents

• Run clarify docs once. It lists every command, flag, and body field in about 6,000 tokens.
• When stdout is not a terminal, output is JSON. Errors go to stderr as {"error":{"status":..., "detail":..., "hint":...}}.
• Exit codes: 2 usage, 3 not signed in, 4 not found, 5 invalid input, 6 rate limited, 7 server error, 8 network, 9 forbidden.
• -f keeps only the fields you name, -o tsv prints one row per record, and --dry-run prints a request without sending it.
• Without a browser, sign in in two steps: clarify login --no-wait prints a link and code for a person to approve, then clarify login --device-code <code> finishes.

Telemetry

The CLI sends a usage event to Clarify for each command it runs, and a second one when the command fails, so we can see which commands people and agents use. Each event carries:

• The command, its group and verb, and whether it was generated from the API reference.
• The names of the flags you passed, the tool's name for clarify tools, and the HTTP method for clarify api.
• The exit code and how long the command took. A failure adds the kind of error, the HTTP status, and the API's error code.
• The output format, whether output went to a terminal, whether you passed --dry-run or opened a help page, and whether a .clarify.json pins the directory.
• The CLI version, OS, and architecture, whether it ran in CI, and the coding agent that ran it, if any.
• Whether you used a session or an API key, and the workspace if you belong to it, saved a key for it, or the API accepted your key for it, with its organization when known.

When you're signed in, events are tied to your Clarify user, as they are in the web and desktop apps. Otherwise they carry a random ID for this machine, and when you sign in, the machine's earlier events are tied to you too. Events never carry argument or flag values, paths, SQL, record data, or error messages.

Turn it off for every profile with clarify config set telemetry off, CLARIFY_TELEMETRY=off, or DO_NOT_TRACK=1. clarify config shows whether it's on.