Cleotic CLI
The Cleotic CLI, cleotic, sets up brands, competitors, segments and prompts from a terminal, and exports the evidence behind your answers as JSON for scripts and benchmarks. It runs on macOS and Linux. For an AI assistant, use Connected Agents instead.
Install
curl -fsSL https://cleotic.sh/install | sh
The script downloads the latest release for your machine, verifies its checksum and installs cleotic in ~/.local/bin:
Resolved latest release: v0.5.0
Detected: linux x86_64
Downloading: cleotic_0.5.0_linux_x86_64.tar.gz
Verified checksum
Installed cleotic to /home/you/.local/bin/cleotic
Run: cleotic auth login
If that directory isn't on your PATH, the script says so; add it before you run cleotic. To install a particular version, or somewhere else:
curl -fsSL https://cleotic.sh/install | CLEOTIC_VERSION=v0.5.0 CLEOTIC_INSTALL_DIR=/usr/local/bin sh
cleotic update installs the latest release. In an interactive terminal the CLI checks for one at most once a day and prints a notice. It never checks with --json or --no-input, when output is piped, or in CI; set CLEOTIC_NO_UPDATE_CHECK=1 to turn it off everywhere.
Sign in
cleotic auth login
The CLI opens your browser to sign in to Cleotic, then works in the organisation you choose there:
Logged in to Cleotic as you@example.com
Organization: org_01J8Z3…
| Where you are | How to sign in |
|---|---|
| A computer with a browser | cleotic auth login opens it |
| SSH, or no local browser | The CLI prints a link to open on any device, then asks for the code shown after you sign in. --no-browser chooses this yourself. |
| CI and scripts | Create a key in Settings → CLI API keys and set CLEOTIC_API_KEY. It takes precedence over a browser sign-in. |
Your session is kept in the system keychain and refreshed automatically. cleotic auth login --change-org signs in again so you can pick another organisation. cleotic auth status checks the session, and cleotic auth logout removes it from this computer.
If your organisation needs to accept Cleotic's current terms, the CLI opens the app, waits while you accept, and carries on.
Names in the CLI
The CLI uses some older names for things the app has since renamed:
| In the CLI | In the app |
|---|---|
| project | A brand or study. Its project ID is what --project takes. |
| monitor | A segment |
| primary brand | The brand being tracked, set in Brand settings → Details |
Choose a brand
Most commands work on one brand. Find its ID, then make it the default:
cleotic brands list
cleotic projects use proj_01J8Z4…
ID Name Status Access
------------ ---- ------ ------
proj_01J8Z4… Acme active owner
Pass --project <id> to a command to use another brand for that command. cleotic setup creates a brand and its first segment and makes it the default; see setup.
Output
Commands print aligned tables for reading. Add --json for the API's own JSON, pretty-printed, which is the shape to rely on in scripts:
cleotic competitors list --json | jq -r '.[].name'
Questions, progress, warnings and errors go to standard error, so with --json the JSON is all that reaches standard output. cleotic projects summary always prints JSON.
Scripts and CI
In a script, pass --no-input so a command fails instead of waiting for an answer, and --yes to delete without a confirmation prompt:
export CLEOTIC_API_KEY=…
cleotic setup --no-input --brand-name "Acme" --brand-domain acme.com --json
cleotic benchmark bundle --from 2026-09-01 --to 2026-09-30 --json > evidence.json
| Exit code | Meaning |
|---|---|
0 | Success |
1 | The command failed, for example an API error, a cancelled delete or an unknown flag |
2 | Missing or invalid input: a required flag, no brand selected, or a delete or update that needs --yes when it can't ask |
Errors are one plain line on standard error, such as Missing monitor. Pass --monitor, and suggest the fix. Add --debug for request details.
Configuration
| Setting | Set it with | Purpose |
|---|---|---|
default_project_id | cleotic projects use <id> | The brand commands use without --project |
api_url | cleotic config set api-url <url>, CLEOTIC_API_URL or --api-url | The Cleotic API. Defaults to https://api.cleotic.ai. |
| API key | CLEOTIC_API_KEY | Sign-in for CI and scripts |
| Update notices | CLEOTIC_NO_UPDATE_CHECK=1 | Turns off the daily update check |
The settings file is ~/.config/cleotic/config.yaml on Linux and ~/Library/Application Support/cleotic/config.yaml on macOS. cleotic config get shows the settings in use and the file's path; cleotic config reset deletes it.
Related
Updated