CLI command reference

Updated 9 November 2026 · 10 min read
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.

FlagEffect
--jsonPrint JSON instead of a table
--no-inputFail instead of prompting for missing input
--debugPrint 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>
FlagDescription
--urlThe brand's website. You can also pass it as the first argument.
--marketThe 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

CommandWhat it does
brands listLists your brands
studies listLists your studies
projects listLists 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  shared

JSON lists include id, name, status, access_mode, scope_kind, website_url, created_at and updated_at.

cleotic primary-brand

The brand a project tracks.

CommandWhat it does
showShows the tracked brand
setCreates 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  active

cleotic competitors

The brands you compare against.

CommandWhat it does
listLists 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.

CommandWhat it does
listLists 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  12

A 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>.

CommandWhat it does
listLists 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 workflows

cleotic benchmark

Exports the evidence behind a brand's answers for analysis outside Cleotic. Built for --json; without it, each command prints a table.

CommandWhat it exportsTable columns
observationsEach model run: prompt, model, status, answer text, latency, tokens and costCaptured, Batch, Run, Model, Status, Batch Health, Latency, Tokens, CostMC (cost in microcents)
derived-factsWhat Cleotic found in each answer: brand mentions, citations, recommendations and outcomes, with confidence and evidence textCaptured, Type, Response, Batch, Entity, Value, Conf, Extractor, Evidence
sourcesCited sources with their ownership, category, sentiment and signalsCaptured, Citation, Source, Ownership, Category, Angle, Sentiment, Brands, Signals
missing-dataAnswers whose analysis is still pending or failedCaptured, Severity, Kind, Status, Batch, Response, Message
bundleAll of the above, plus extraction status, in one JSON document with the filters usedA count of rows per dataset

Every benchmark command takes:

FlagFilters to
--from, --toDays, YYYY-MM-DD
--segment, --prompt, --batchOne segment, prompt or collection batch, by ID
--modelOne model or surface
--market, --language, --category, --intent-typePrompts with that label
--limit, --offsetA page of rows: 100 by default

Some commands add their own:

CommandFlags
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       0

That'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
CommandWhat 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
FlagDescription
show --waitWaits 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-24

With --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
CommandWhat 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.
FlagDescription
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
CommandWhat 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
FlagDescription
--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      11

With --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
CommandWhat 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
FlagDescription
--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-17

With --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

CommandWhat it does
loginSigns in through the browser. --no-browser prints a link to open on another device; --change-org lets you pick another organisation.
statusChecks the session with Cleotic and shows who you're signed in as, the organisation and when the token expires
logoutRemoves the session from this computer

cleotic config

CommandWhat it does
getShows api_url, default_project_id and the settings file's path
set api-url <url>Saves the API URL
resetDeletes the settings file, including the default brand

cleotic update and version

CommandWhat it does
cleotic updateInstalls the latest release after asking. --yes skips the question; --check only reports whether one is available.
cleotic versionPrints the version, commit and build date

cleotic completion bash, zsh, fish or powershell prints a shell completion script.