Cleotic CLI

Updated 18 October 2026 · 4 min read
On this page

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 areHow to sign in
A computer with a browsercleotic auth login opens it
SSH, or no local browserThe 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 scriptsCreate 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 CLIIn the app
projectA brand or study. Its project ID is what --project takes.
primary brandThe 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. 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.json

To 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 70

To 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-input

To 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.csv

To 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 codeMeaning
0Success
1The command failed, for example an API error or a cancelled delete
2Missing 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
3A 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

SettingSet it withPurpose
default_project_idcleotic projects use <id>The brand commands use without --project
api_urlcleotic config set api-url <url>, CLEOTIC_API_URL or --api-urlThe Cleotic API. Defaults to https://api.cleotic.ai.
API keyCLEOTIC_API_KEYSign-in for CI and scripts
Update noticesCLEOTIC_NO_UPDATE_CHECK=1Turns 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.