CLI command reference
On this page
Every cleotic command, its flags and what it prints. Each command also has --help. To install the CLI and sign in, see Cleotic CLI.
Global flags
These work on every command.
| Flag | Effect |
|---|---|
--json | Print JSON instead of a table |
--no-input | Fail instead of prompting for missing input |
--debug | Print request details to standard error |
--api-url <url> | Use another Cleotic API for this command |
Commands that work on one brand use the default, set with cleotic projects use, unless you pass --project <id> or a [project-id] argument.
cleotic setup
Sets up a brand from its website, the way the app does. Cleotic reads the site and proposes the brand, its competitors, a segment and prompts. You review them, and the brand is created when you approve. The new brand becomes the default.
cleotic setup acme.com
cleotic setup acme.com --no-input --market GB --json
cleotic setup --resume <setup-id>| Flag | Description |
|---|---|
--url | The brand's website. You can also pass it as the first argument. |
--market | The market to track: a two-letter country code such as GB, or global. Defaults to the proposed market. |
--resume <setup-id> | Continues a setup that is waiting for approval |
In a terminal, setup shows the proposals, then asks you to confirm the market and choose which competitors and prompts to keep. With --no-input, or without a terminal, it keeps every proposal.
Reading the website...
Finding the brand and its competitors...
Writing prompts...
Brand: Acme (acme.com)
Competitors: Rival (rival.com)
Segment: Acme AI visibility, GB, en
Prompts:
- Which expense tools work best for a small team?
Set up Acme
Using project proj_01J8Z4…Setup checks your plan's capacity before it approves. If the brand doesn't fit, the error says what to free up and how to resume. With --json, setup prints {"setup_id", "project_id", "segment_id", "prompt_ids"}.
Setup needs a signed-in user, so run cleotic auth login first. An API key can't set up a brand from its website. In a script that uses an API key, build the brand with projects create, primary-brand set and segments create.
cleotic brands, studies and projects
| Command | What it does |
|---|---|
brands list | Lists your brands |
studies list | Lists your studies |
projects list | Lists every brand and study |
projects use <id> | Makes a brand or study the default for later commands. Doesn't call the API. |
projects show [project-id] | Shows one |
projects create --name <name> | Creates a project. --status sets its status. |
projects update [project-id] | Renames it (--name) or changes its status (--status) |
projects delete [project-id] | Deletes it and everything in it. Asks first; --yes skips the question. |
projects summary [project-id] | Prints its metrics, segments, competitors, reports and tracking as JSON |
ID Name Status Access
------------ ------- ------ ------
proj_01J8Z4… Acme active owner
proj_01J9A2… Acme EU paused sharedJSON lists include id, name, status, access_mode, scope_kind, website_url, created_at and updated_at.
cleotic primary-brand
The brand a project tracks.
| Command | What it does |
|---|---|
show | Shows the tracked brand |
set | Creates or edits it: --name, --domain, and --alias, repeated for each alias |
--alias replaces the existing aliases, so pass all of them. Changing the name or aliases re-reads existing answers.
ID Name Domain Aliases Status
----------- ---- -------- -------------- ------
brand_01J8… Acme acme.com Acme Inc, ACME activecleotic competitors
The brands you compare against.
| Command | What it does |
|---|---|
list | Lists competitors |
create --name <name> | Adds one, with optional --domain and repeated --alias |
update <competitor-id> | Edits --name, --domain, --alias or --status (active or paused) |
delete <competitor-id> | Stops tracking it. Asks first; --yes skips the question. |
Output has the same columns as primary-brand. A new competitor uses one tracked brand of your plan; pausing keeps its history and frees the capacity.
cleotic segments
Segments: groups of prompts with a market and language. list and create work on one brand; the others take the segment's ID.
| Command | What it does |
|---|---|
list | Lists segments |
create --name <name> | Adds one, with optional --geo (a country code such as GB, or global), --language (such as en) and --prompt-limit |
show <segment-id> | Shows one |
update <segment-id> | Changes --name, --geo, --language, --prompt-limit or --status |
delete <segment-id> | Deletes it with its prompts and their answers. Asks first; --yes skips the question. |
ID Name Status Geo Lang Models Prompts
----------- ------------------ ------ --- ---- -------------------------------- -------
mon_01J8Z5… Acme AI visibility active GB en openai:consumer, google:consumer 12A segment collects from every model your plan includes, listed by provider; the CLI can't choose models. show, create and update print prompts as used/limit, such as 12/25.
cleotic prompts
Every prompts command needs --segment <segment-id>.
| Command | What it does |
|---|---|
list | Lists the segment's prompts |
create --text <question> | Adds one, with optional repeated --tag and --status. It's answered straight away. |
update <prompt-id> | Changes --status or --tag. To change the wording, use replace. |
replace <prompt-id> --text <question> | Replaces the wording with a new prompt; the old one keeps its answers in its history |
delete <prompt-id> | Deletes it and its answers. Asks first; --yes skips the question. |
ID Status Tags Text
----------- ------ ---------- -----------------------------------------------
prm_01J8Z6… active pricing Which expense tools work best for a small team?
prm_01J8Z7… paused comparison Compare Acme and Rival for approval workflowscleotic benchmark
Exports the evidence behind a brand's answers for analysis outside Cleotic. Built for --json; without it, each command prints a table.
| Command | What it exports | Table columns |
|---|---|---|
observations | Each model run: prompt, model, status, answer text, latency, tokens and cost | Captured, Batch, Run, Model, Status, Batch Health, Latency, Tokens, CostMC (cost in microcents) |
derived-facts | What Cleotic found in each answer: brand mentions, citations, recommendations and outcomes, with confidence and evidence text | Captured, Type, Response, Batch, Entity, Value, Conf, Extractor, Evidence |
sources | Cited sources with their ownership, category, sentiment and signals | Captured, Citation, Source, Ownership, Category, Angle, Sentiment, Brands, Signals |
missing-data | Answers whose analysis is still pending or failed | Captured, Severity, Kind, Status, Batch, Response, Message |
bundle | All of the above, plus extraction status, in one JSON document with the filters used | A count of rows per dataset |
Every benchmark command takes:
| Flag | Filters to |
|---|---|
--from, --to | Days, YYYY-MM-DD |
--segment, --prompt, --batch | One segment, prompt or collection batch, by ID |
--model | One model or surface |
--market, --language, --category, --intent-type | Prompts with that label |
--limit, --offset | A page of rows: 100 by default |
Some commands add their own:
| Command | Flags |
|---|---|
derived-facts | --fact-type (brand_mention, citation, citation_brand_match, recommendation_fact or response_outcome) and --entity |
sources | --domain, --ownership (own, competitor or third_party), --source, --citation, --source-type, --source-category, --content-angle, --source-sentiment and --citation-context |
missing-data | --kind, --status and --include-optional, which adds optional classifications |
bundle | --include-optional |
Dataset Rows
----------------- ----
observations 312
derived_facts 1840
source_evidence 426
extraction_status 312
missing_data 0That's bundle without --json.
cleotic readiness
Reads a brand's site readiness: how ready its website is for AI answer engines, scored out of 100. Cleotic scans each brand's site once a week, and the first scan starts when the brand gets a website. The CLI reads scans but can't start one, because after the first scan, scans only run on the weekly schedule. Reading is free and works with an API key.
cleotic readiness show
cleotic readiness show --wait --fail-under 70
cleotic readiness issues --json| Command | What it does |
|---|---|
show [project-id] | Shows the latest finished scan: its score, verdict and open issues, and the date of the next scan |
issues [project-id] | Lists the open issues of the latest finished scan in fix order, with their severity, the pages they affect, the points a fix should recover and their check ID |
| Flag | Description |
|---|---|
show --wait | Waits up to 30 minutes for a scan that is still running |
show --fail-under <score> | Exits with code 3 when the score is below <score>, so a CI step can gate on it. Exits with 1 when there is no finished scan to check. |
issues --scan <scan-id> | Lists the issues of another scan. show prints the latest scan's ID. |
Scan Status Site readiness Open issues Completed
------------------------------------ -------- ------------------- ---------------------------------------- ----------
6d5cd34d-f1d8-4cd1-92ba-626832694dcb complete 62/100 (Needs work) 20: 1 critical, 6 major, 9 minor, 4 info 2026-10-17
Next scan: 2026-10-24With --json, show prints {"scan", "newer_scan", "next_scan_at", "rubric_notice"}. Each scan has an id, a status (queued, processing, complete or failed), the url scanned, its score, verdict and open_issues once it is complete, and completed_at. newer_scan is a scan newer than scan that is still running or failed. rubric_notice is the latest change to how this brand's scans are scored, with its rubric_version, date and summary, or null if there hasn't been one. Without --json, show prints it after the table. A --fail-under gate can pass or fail differently after a change. issues --json prints the API's list of issues, every page in one document.
cleotic opportunities
Reads a brand's opportunities, the inbox of gaps Cleotic found, and moves them between stages. A script can copy them into a ticket tracker or a report, then move each one on when its work ships. Reading and moving opportunities is free and works with an API key.
cleotic opportunities list --stage now --type readiness
cleotic opportunities show <opportunity-id>
cleotic opportunities move <opportunity-id> --stage watching| Command | What it does |
|---|---|
list [project-id] | Lists the brand's open opportunities, ordered by stage, then score. Like the app's Active view, it leaves out snoozed and dismissed items. |
show <opportunity-id> | Shows one opportunity with its signal and the facts behind it |
move <opportunity-id>... | Moves one or more opportunities to a stage. They all move or none do. |
| Flag | Description |
|---|---|
list --stage <stage> | Lists only one stage: now, in_flight, watching or won |
list --type <type> | Lists only one type: content_gap, readiness, source_gap, traffic_gap, coverage_gap or correction |
list --segment <segment-id> | Lists only one segment's opportunities. Readiness issues, source gaps, traffic gaps and corrections have no segment, so this leaves them out. |
move --stage <stage> | The stage to move to. Required. |
Move an opportunity to watching when its work ships, as Done does in the app. For a readiness issue this records the fix as shipped, for a source gap the outreach as sent, and for a traffic gap the page as optimised. Cleotic then watches the evidence, and moves it back to now if the gap reappears. Move it to won once the gap has closed. Cleotic never sets won itself.
ID Stage Type Score Title
------------------------------------ ----- ----------- ----- --------------------------------------------------
dbd5e3f4-f897-49a5-80b1-8c75de723cfd Now Readiness 84 Clickjacking protection
0ca13dd5-d303-4da6-ab3d-fb0057f6c531 Now Content gap 70 How many driving lessons do I need before my test?With --json, list prints the API's {"items", "counts", "sync"}: every opportunity in one document, the stage counts and when Cleotic last refreshed the list. show prints the API's opportunity, with its play, history, comments and evidence, and move prints {"items"} with the moved opportunities.
cleotic ai-traffic
Exports a brand's AI traffic for a date range, so a scheduled job can load it into a spreadsheet or BI tool. It counts two things: requests from AI crawlers, and visits people make from an AI assistant (AI referrals). Crawler requests include answer fetches, the pages an AI assistant fetches while it answers someone's question. Crawler requests and AI referrals are separate counts and are never added together. Reading AI traffic is free and works with an API key.
cleotic ai-traffic summary --from 2026-10-01 --to 2026-10-31
cleotic ai-traffic pages --from 2026-10-01 --to 2026-10-31 --json| Command | What it does |
|---|---|
summary [project-id] | Shows the totals from the app's AI traffic overview: AI referrals, answer fetches, crawler requests and AI share, then referrals, crawls and pages for each provider |
pages [project-id] | Lists every page AI crawlers requested or AI assistants sent visits to, as in the app's Paths tab, most requested first |
| Flag | Description |
|---|---|
--from <date>, --to <date> | The first and last day to read, as YYYY-MM-DD in UTC. Pass both or neither. Without them the commands read the last 30 days. |
Both commands count what the app counts by default: AI crawlers and AI-referred visits to pages on the brand's own site, with brand rules applied and spoofed crawlers left out. Your plan's history limit can shorten the period, and the output always shows the period it read.
Period: 2026-09-17 to 2026-10-17
Metric Count Detail
---------------- ----- ------------------------------
AI referrals 264 Visits from AI assistants
Answer fetches 59 59 verified
Crawler requests 345 134 search index, 152 training
AI share 11.0% of 2410 visits by people
Provider Referrals Crawls Pages
---------- --------- ------ -----
OpenAI 72 201 11
Anthropic 64 66 11With --json, summary prints one JSON object with the totals in ai_referrals, crawler_visits and ai_share_pct. It includes over_time, one row per day with that day's visits by people, AI referrals and crawler requests, for a daily series. systems has the counts by provider, crawlers by crawler with its purpose, and excluded the requests from other bots and hosts that aren't counted. pages --json prints {"view", "period", "total", "paths"} with every page in one document. Each path has its crawls, referrals, ai_share_pct and last_seen_at.
cleotic reports
Lists, reads and creates a brand's reports, so a monthly job can create each client's report and pass its public link on. A report is a snapshot of the brand's results for a date range, compared with the same number of days before. Anyone with its public link can read it without a Cleotic account. All three commands work with an API key.
cleotic reports create --no-input --json | jq -r .share_url
cleotic reports list --json| Command | What it does |
|---|---|
list [project-id] | Lists every report of the brand, as on its Reports page, newest first |
show <report-id> | Shows a report's period, status, public link and the summary readers see. Takes --project |
create [project-id] | Creates a report and prints its public link. The link works at once and shows the report once its figures are built, usually within a minute |
| Flag | Description |
|---|---|
--from <date>, --to <date> | create only. The first and last day the report covers, as YYYY-MM-DD in UTC. Pass both or neither. Without them it covers last calendar month, as the app does. |
--name <name> | create only. The name readers see, up to 120 characters. Without it the report is named as in the app, such as Roadschool AI visibility report · September 2026, or Report when that would be too long. |
Listing and reading reports is free. Creating one uses one report of plan capacity, and model budget for the summary written with AI. Editing, sending, revoking and deleting reports stay in the app. Sending emails your client, and a revoked link can't be restored.
ID Name Period For Status Created
------------------------------------ ------------------------------------------------ ------------------------ ------ ------ ----------
36439005-0fca-42dc-a9b5-b98aa1754d5b Roadschool AI visibility report · September 2026 2026-09-01 to 2026-09-30 Client Ready 2026-10-17
bb3808f3-5bfa-5469-917b-6c652240d39e Last 30 days 2026-09-17 to 2026-10-17 Client Ready 2026-10-17With --json, list prints an array of reports, each with id, name, date_from, date_to and status, and show prints one report with its summary and the addresses it was sent to. create prints the new report with "status": "building"; show reports ready once it is built. Each report has share_url, its public link, while the link works. It is left out once the report is revoked.
cleotic auth
| Command | What it does |
|---|---|
login | Signs in through the browser. --no-browser prints a link to open on another device; --change-org lets you pick another organisation. |
status | Checks the session with Cleotic and shows who you're signed in as, the organisation and when the token expires |
logout | Removes the session from this computer |
cleotic config
| Command | What it does |
|---|---|
get | Shows api_url, default_project_id and the settings file's path |
set api-url <url> | Saves the API URL |
reset | Deletes the settings file, including the default brand |
cleotic update and version
| Command | What it does |
|---|---|
cleotic update | Installs the latest release after asking. --yes skips the question; --check only reports whether one is available. |
cleotic version | Prints the version, commit and build date |
cleotic completion bash, zsh, fish or powershell prints a shell completion script.