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 | shThe 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 loginIf 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 shcleotic 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 loginThe 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. |
| 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 ownerPass --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. cleotic readiness show --json prints a short summary of the latest scan rather than the API's full report.
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=…
PROJECT_ID="$(cleotic projects create --name "Acme" --json | jq -r .id)"
cleotic primary-brand set --project "$PROJECT_ID" --name "Acme" --domain acme.com --json
cleotic segments create --project "$PROJECT_ID" --name "Acme AI visibility" --json
cleotic benchmark bundle "$PROJECT_ID" --from 2026-09-01 --to 2026-09-30 --json > evidence.jsonTo fail a CI step when a brand's site readiness drops below a score, check the latest scan:
cleotic readiness show "$PROJECT_ID" --fail-under 70To copy a brand's open readiness findings into a ticket tracker, and mark one as shipped when its ticket closes:
cleotic opportunities list "$PROJECT_ID" --stage now --type readiness --json \
| jq -r '.items[] | [.id, .title] | @tsv'
cleotic opportunities move "$OPPORTUNITY_ID" --project "$PROJECT_ID" --stage watching --no-inputTo load last month's AI traffic into a spreadsheet, one row per day and one row per page:
cleotic ai-traffic summary "$PROJECT_ID" --from 2026-09-01 --to 2026-09-30 --json \
| jq -r '.over_time[] | [.date, .ai_referrals, .crawler_visits, .total_visits] | @csv' > ai-traffic-daily.csv
cleotic ai-traffic pages "$PROJECT_ID" --from 2026-09-01 --to 2026-09-30 --json \
| jq -r '.paths[] | [.path, .crawls, .referrals] | @csv' > ai-traffic-pages.csvTo create each brand's report for last month on the first of the month, and collect the links to send:
for project in $(cleotic brands list --json | jq -r '.[].id'); do
cleotic reports create "$project" --no-input --json | jq -r '[.name, .share_url] | @tsv'
done > reports.tsv| Exit code | Meaning |
|---|---|
0 | Success |
1 | The command failed, for example an API error or a cancelled delete |
2 | Missing or invalid input: an unknown flag, a flag value that isn't valid, a required flag, no brand selected, or a delete or update that needs --yes when it can't ask |
3 | A check ran and failed: readiness show --fail-under found a score below the threshold |
Errors are one plain line on standard error, such as Missing segment. Pass --segment, 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.