Skip to content
checkenddocs

CLI reference

View as Markdown

The ce client runs on a laptop, in CI or in an agent sandbox. The checkend server binary also contains all ce commands.

Usage: ce <command> [flags]


Commands:
  annotate     Record a change, a release or a note on a site
  annotations  List the annotations of a site
  audit        Show the audit log of writes by tokens (admin)
  brief        Show the brief: top changes, findings, annotations, outcomes
  context      List the contexts, or select one
  crawlers     Show the AI and search crawler hits of a site (from pushed access logs)
  event        Send one custom event from a server or a script
  findings     List, show, claim, finish, dismiss, reopen and remeasure findings
  goals        List, add and delete the goals of a site
  health       Show the health of the server: disk, event log, backups, jobs (admin)
  indexnow     Show, set and use the IndexNow submit of changed URLs of a site
  invites      List and revoke invites (admin); accept an invite link with a token
  login        Log in to a server: in the browser (device flow), or with an API token
  logout       Remove a context and its token
  logs         Push a web server access log, for the AI crawler data
  mcp          Run a stdio MCP server that forwards each tool to the server's /mcp endpoint
  pages        Show what the crawler found on the pages of a site (title, H1, indexability)
  passkeys     List and delete the passkeys of your user (add one in the web UI, Settings)
  people       List people, invite a person, change a role, remove a person (admin)
  projects     List projects, set the daily event limit (admin)
  query        Show page views, visitors, top pages and conversions of a site
  report       Show, list and make reports, and manage the report schedules
  retention    Show or set the raw-data retention of each module (admin)
  search       Show Search Console and Bing rows; connect, check, sync and disconnect the sources
  setup        Make the first admin with the setup token, and log in
  sites        List, add, change, delete and verify sites
  tokens       List, create and revoke API tokens (admin; each person: own tokens)
  vitals       Show the web vitals (p75 of LCP, INP, CLS, TTFB) of a site and its pages
  webhooks     Add, list, delete and test webhooks (admin)
  version      Show the version


Run "ce <command> --help" for the flags and examples of a command.
For CI and agents, set CHECKEND_URL and CHECKEND_TOKEN.
On a pipe, stdout has one JSON value and an error is a JSON object on stderr.
Exit codes: 0 OK, 1 error, 2 not authenticated or no server, 3 not found,
4 no data yet, 5 forbidden (the token has no scope for the action).
Command What it does
ce annotate Record a change, a release or a note on a site
ce annotations List the annotations of a site
ce audit Show the audit log of writes by tokens (admin)
ce brief Show the brief: top changes, findings, annotations, outcomes
ce context List the contexts, or select one
ce crawlers Show the AI and search crawler hits of a site (from pushed access logs)
ce event Send one custom event from a server or a script
ce findings List, show, claim, finish, dismiss, reopen and remeasure findings
ce goals List, add and delete the goals of a site
ce health Show the health of the server: disk, event log, backups, jobs (admin)
ce indexnow Show, set and use the IndexNow submit of changed URLs of a site
ce invites List and revoke invites (admin); accept an invite link with a token
ce login Log in to a server: in the browser (device flow), or with an API token
ce logout Remove a context and its token
ce logs Push a web server access log, for the AI crawler data
ce mcp Run a stdio MCP server that forwards each tool to the server’s /mcp endpoint
ce pages Show what the crawler found on the pages of a site (title, H1, indexability)
ce passkeys List and delete the passkeys of your user (add one in the web UI, Settings)
ce people List people, invite a person, change a role, remove a person (admin)
ce projects List projects, set the daily event limit (admin)
ce query Show page views, visitors, top pages and conversions of a site
ce report Show, list and make reports, and manage the report schedules
ce retention Show or set the raw-data retention of each module (admin)
ce search Show Search Console and Bing rows; connect, check, sync and disconnect the sources
ce setup Make the first admin with the setup token, and log in
ce sites List, add, change, delete and verify sites
ce tokens List, create and revoke API tokens (admin; each person: own tokens)
ce vitals Show the web vitals (p75 of LCP, INP, CLS, TTFB) of a site and its pages
ce webhooks Add, list, delete and test webhooks (admin)
ce version Show the version

ce annotate

Section titled “ce annotate”

Record a change, a release or a note on a site.

Usage: ce annotate <site> "<text>" [--kind agent_change|release|note] [--date <date>]
                   [--finding <finding id>] [--link <url>] [--dry-run]


Records a change on a site at a time, so that Checkend can measure it. Agents
record each change that they make (kind agent_change, the default). CI records
releases (kind release). --date is RFC 3339 or a UTC date; default now.
Needs write access to the site's project.


Examples:
  ce annotate example.com "Title changed on /pricing" --finding f_8k2 --link https://github.com/acme/web/pull/7
  ce annotate example.com "v1.4.0" --kind release


Flags:
  -context string
      the context to use (see "ce context list")
  -date string
      the time of the change: RFC 3339 or a UTC date (default now)
  -dry-run
      show the change, do not make it
  -finding string
      the ID of the finding that the change is for
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -kind string
      agent_change (default), release or note
  -link string
      a URL about the change, for example the pull request
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce annotations

Section titled “ce annotations”

List the annotations of a site.

Usage: ce annotations list <site> [--period 24h|7d|30d|365d]


Lists the annotations of a site (agent changes, releases, notes), newest first.


Example:
  ce annotations list example.com --period 7d


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -period string
      the period: 24h, 7d, 30d (default) or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce audit

Section titled “ce audit”

Show the audit log of writes by tokens (admin).

Usage: ce audit [--limit 100] [--token <token id>] [--action <action>] [--before <entry id>]


Prints the audit log, newest first: each write by a token (sites, goals,
tokens, annotations, findings, webhooks), with the token, its scopes and the
interface (rest, mcp, cli, ui or job). Admin only.


Example:
  ce audit --token tok_0192... --limit 20
  ce audit --action finding


Flags:
  -action string
      only these writes: an action (finding.claim) or its first part (finding)
  -before string
      only entries older than this entry ID (the next page)
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      the most entries (default 100, at most 500)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -token string
      only the writes of this token ID
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce brief

Section titled “ce brief”

Show the brief: top changes, findings, annotations, outcomes.

Usage: ce brief [<site>] [--project <id>] [--period 24h|7d|30d|365d]


Prints the brief: the top changes against the period before (with a
significance test), the open findings, the annotations and releases, the
outcomes of earlier changes and the data date of each site. Without a site or
a project: all sites that the token can read. Agents: start here.


Examples:
  ce brief example.com
  ce brief --project prj_default --period 30d --json


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -period string
      the period: 24h, 7d (default), 30d or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -project string
      one project
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce context

Section titled “ce context”

List the contexts, or select one.

Usage: ce context list
       ce context use <name>


"list" shows each context with its server URL and the store of its token:
keychain (the OS keychain) or file (the credentials file, when no keychain
works).


Flags:
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)

ce crawlers

Section titled “ce crawlers”

Show the AI and search crawler hits of a site (from pushed access logs).

Usage: ce crawlers <site> [--period 24h|7d|30d|365d] [--bot <name>] [--limit 20]


Shows the hits of AI and search crawlers (GPTBot, ClaudeBot, PerplexityBot,
Googlebot, Bingbot and others) on the pages of a site, from the access logs that
you push with "ce logs push". A JavaScript tag cannot see crawlers. Exit code 4
means that the period has no crawler hits yet.


Examples:
  ce crawlers example.com --period 7d
  ce crawlers example.com --bot GPTBot --json


Flags:
  -bot string
      one crawler, for example GPTBot
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      the most pages (default 20)
  -period string
      24h, 7d, 30d (default) or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce event

Section titled “ce event”

Send one custom event from a server or a script.

Usage: ce event send <site> --name <event name> [--revenue <amount> --currency <ISO 4217>]
                     [--prop key=value]... [--page-url <page URL>] [--vid <visitor id>] [--dry-run]


Sends one custom event from a server or a script, for example a purchase from a
payment webhook. Needs a token with write access to the site's project. The
server keeps no IP address, user agent or location for it. --vid gives a visitor
ID only for a site in extended privacy mode.


Examples:
  ce event send example.com --name Signup
  ce event send example.com --name Purchase --revenue 49.90 --currency USD --prop plan=pro


Flags:
  -context string
      the context to use (see "ce context list")
  -currency string
      the ISO 4217 currency code of the revenue, for example USD
  -dry-run
      show the event, do not send it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -name string
      the custom event name (required)
  -page-url string
      the page URL on the site (default: https://<site>/)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -prop value
      a custom property key=value (repeat the flag for more)
  -revenue string
      the revenue amount, for example 49.90 (needs --currency)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -vid string
      a persistent visitor ID (extended privacy mode only)

ce findings

Section titled “ce findings”

List, show, claim, finish, dismiss, reopen and remeasure findings.

Usage: ce findings list [--site <site>] [--project <id>] [--status open,claimed] [--limit 50]
                        [--token <token name>] [--action <type,...>] [--period 24h|7d|30d|365d]
       ce findings show <id>
       ce findings claim <id> [--note <text>] [--dry-run]
       ce findings done <id> (--annotation <annotation id> | --text "<change>" [--link <url>] [--date <date>]) [--note <text>] [--dry-run]
       ce findings dismiss <id> [--note <text>] [--dry-run]
       ce findings reopen <id> [--note <text>] [--dry-run]
       ce findings remeasure <id> [--note <text>] [--dry-run]
       ce findings run


A finding is a fact that a rule found, with evidence. Claim a finding before
you work on it. "done" needs the annotation of the change; Checkend starts to
measure on the next UTC day, and sets the outcome when the 14 days after the
change day are complete: worked, got_worse, no_clear_change or
too_few_to_compare. got_worse means that the change made the metric worse.
"remeasure" computes the outcome again and keeps the history (admin).
--dry-run asks the server to check the change without making it. "run" runs
the rules and the outcomes now (admin; the job runs each hour).


Examples:
  ce findings list --status open
  ce findings claim f_8k2
  ce findings done f_8k2 --text "Title changed on /pricing" --link https://github.com/acme/web/pull/7


Flags:
  -action string
      list: action types, comma-separated, for example fix_redirect
  -annotation string
      done: the ID of the annotation of the change
  -context string
      the context to use (see "ce context list")
  -date string
      done: the time of the change for the new annotation (default now)
  -dry-run
      check the change on the server, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      list: the most findings (default 50)
  -link string
      done: a URL about the change for the new annotation
  -note string
      a note for the history
  -period string
      list: only findings with a change in this period: 24h, 7d, 30d or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -project string
      list: one project
  -site string
      list: one site
  -status string
      list: statuses, comma-separated (default: all)
  -text string
      done: the text of a new annotation of the change
  -token string
      list: only the findings that this token (name) claimed
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce goals

Section titled “ce goals”

List, add and delete the goals of a site.

Usage: ce goals list <site>
       ce goals add <site> <name> (--event <event name> | --page <path pattern>) [--dry-run]
       ce goals delete <site> <goal id> [--yes] [--dry-run]


A goal is a custom event name (--event, for example Signup) or a page path
pattern (--page, for example /pricing or /blog/*; "*" matches any characters).
"ce query <site>" shows the conversions, the conversion rate and the revenue
of each goal. "add" and "delete" need write access to the site's project.


Examples:
  ce goals add example.com signup --event Signup
  ce goals add example.com pricing --page '/pricing*'
  ce goals list example.com --plain
  ce goals delete example.com goal_0192... --yes


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -event string
      add: the custom event name of the goal
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -page string
      add: the page path pattern of the goal
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -yes
      delete without a question

ce health

Section titled “ce health”

Show the health of the server: disk, event log, backups, jobs (admin).

Usage: ce health


Shows the health report of the server (GET /v1/health/detail): the disk use and
the disk guard, the data folder and secret.key, the GeoIP file, the DuckDB
extensions, the event log and the writer lag, the backups, and the newest run
and error of each job (rules, outcomes, search sync, crawl, rollups,
retention, compaction, backup, disk guard, webhooks). Admin only. On the
server, "checkend doctor" checks the files directly.


Exit codes: 0 when the status is ok or warn, 1 when it is fail (D62), so that a
monitor can run "ce health".


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce indexnow

Section titled “ce indexnow”

Show, set and use the IndexNow submit of changed URLs of a site.

Usage: ce indexnow status <site>
       ce indexnow set <site> (--on | --off) [--mode proxy|manual] [--new-key]
       ce indexnow submit <site> <url>... [--reason <text>]


IndexNow tells Bing and the other IndexNow search engines that pages changed.
Checkend sends the pages that the crawler finds changed, the pages of agent
changes (annotations on a finding with a page) and the URLs of "submit". A job
sends the queue every 10 minutes, at most 1,000 URLs a day for each site.


The search engines check a key file at https://<site>/<key>.txt. With --mode
proxy (default) Checkend serves it at /indexnow/<key>.txt: add the proxy snippet
of "status" to the web server of the site. With --mode manual, put the file in
the web root yourself. "set" needs an admin token.


Examples:
  ce indexnow set example.com --on
  ce indexnow status example.com
  ce indexnow submit example.com https://example.com/pricing --reason "new prices"


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -mode string
      set: proxy or manual
  -new-key
      set: make a new key
  -off
      set: turn IndexNow off
  -on
      set: turn IndexNow on
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -reason string
      submit: why the pages changed
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce invites

Section titled “ce invites”

List and revoke invites (admin); accept an invite link with a token.

Usage: ce invites list
       ce invites revoke <id> [--dry-run]
       ce invites accept <link> [--name <context>]


"list" and "revoke" are for an admin. Make an invite with "ce people invite".
"accept" is for the invited person, where a passkey cannot work (an IP
address, or plain HTTP): it accepts the link and makes an API token with the
scopes of the role, then stores the token as "ce login" does. In a browser on
HTTPS, open the link and register a passkey instead.


Example:
  ce invites accept 'https://stats.example.com/invite#ceinv_...'


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -name string
      accept: the context name (default: the server host)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce login

Section titled “ce login”

Log in to a server: in the browser (device flow), or with an API token.

Usage: ce login <url> [--name <context>] [--scope <scope>]... [--no-browser]
       ce login <url> --device
       echo "$TOKEN" | ce login <url> [--name <context>]
       ce login <url> --token-stdin


Without a pasted token, ce login runs the device flow: it prints a URL and a
code, and opens the browser on a terminal. Sign in there (a passkey), check
the code and approve. Then ce gets a token of your person, with the scopes of
your role, or the --scope values (never more than the role).
On a pipe, the URL and the code are a JSON line on stderr ("notice":
"device_code"), and stdout has the JSON result. --device starts the device
flow without a read of stdin.


With a token on stdin (a pipe), or --token-stdin (a hidden prompt on a
terminal), ce checks the token. Make a token with "ce tokens create".


ce stores the token in the OS keychain. When no keychain works (a server
without a desktop session, CI), or with CHECKEND_KEYRING=file, the token goes
to the credentials file ~/.config/checkend/credentials (or under
$XDG_CONFIG_HOME), mode 0600. ce says which store it used.
For CI and agents, set CHECKEND_URL and CHECKEND_TOKEN instead.


Examples:
  ce login https://checkend.example.com
  ce login https://checkend.example.com --scope 'read:*'
  echo "$TOKEN" | ce login https://checkend.example.com --name work


Flags:
  -device
      use the device flow (the browser); do not read stdin
  -name string
      the context name (default: the server host)
  -no-browser
      device flow: do not open the browser
  -scope value
      device flow: a scope to ask for, for example read:* (repeat it; default: the scopes of your role)
  -token-stdin
      read a token from stdin (a hidden prompt on a terminal)

ce logout

Section titled “ce logout”

Remove a context and its token.

Usage: ce logout [<context>]


Removes a context and deletes its token from the store that holds it: the OS
keychain or the credentials file. The token stays valid on the server: revoke
it with "ce tokens revoke <id>".


Flags:

ce logs

Section titled “ce logs”

Push a web server access log, for the AI crawler data.

Usage: ce logs push <site> <file|->


Sends a web server access log to Checkend (at most 10 MB in one push; split a
larger file). Formats: the combined format of Nginx and Apache, and Caddy JSON.
Checkend keeps only the hits of the AI and search crawlers of its list: the day,
the page, the bot and the status. It drops the other lines, and it keeps no IP
address and no user agent. Lines older than 31 days are not kept. The answer
counts the crawler hits that the push found and sent ("hits"). A second push of
the same lines adds nothing to the data, but its answer counts the hits again.
Needs write access to the site's project.


Examples:
  ce logs push example.com /var/log/nginx/access.log
  zcat access.log.2.gz | ce logs push example.com -
  # each day, from cron:
  ce logs push example.com /var/log/nginx/access.log.1


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce mcp

Section titled “ce mcp”

Run a stdio MCP server that forwards each tool to the server’s /mcp endpoint.

Usage: ce mcp [--url <url>] [--context <name>]


Runs a stdio MCP server (JSON-RPC on stdin and stdout) for MCP clients that support
only stdio. It connects to <url>/mcp with the token of the current context (or
CHECKEND_URL and CHECKEND_TOKEN), and it offers the same tools as the server. Each
call goes to the server. Logs and errors go to stderr. ce mcp stops at the end of
stdin.


Example client configuration:
  {"mcpServers": {"checkend": {"command": "ce", "args": ["mcp"],
    "env": {"CHECKEND_URL": "https://checkend.example.com", "CHECKEND_TOKEN": "ce_..."}}}}


Flags:
  -context string
      the context to use (see "ce context list")
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce pages

Section titled “ce pages”

Show what the crawler found on the pages of a site (title, H1, indexability).

Usage: ce pages <site> [--path <path>]


Shows what the Checkend crawler found on the pages of a site: the status, the
title, the meta description, the H1, the canonical URL, the indexability (and
why not), and the newest Search Console URL Inspection. The crawler visits the
pages with traffic or search impressions, at most once a week, and it obeys
robots.txt (User-agent: CheckendBot). Read the current title before you propose
a new one. Exit code 4 means that the crawler has no page of the site yet.


Examples:
  ce pages example.com
  ce pages example.com --path /pricing --json


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -path string
      one page path, for example /pricing
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce passkeys

Section titled “ce passkeys”

List and delete the passkeys of your user (add one in the web UI, Settings).

Usage: ce passkeys list
       ce passkeys delete <id> [--yes]


Lists the passkeys of the person of the token (an admin that ce setup made, or a
web sign-in). A passkey needs a browser: add one in the web UI, Settings,
Passkeys. An agent token has no person and no passkeys.


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -yes
      delete without a question

ce people

Section titled “ce people”

List people, invite a person, change a role, remove a person (admin).

Usage: ce people list
       ce people invite <email> --role <admin|member|viewer> [--dry-run]
       ce people role <id|email> <admin|member|viewer> [--dry-run]
       ce people remove <id|email> [--yes] [--dry-run]


People have one role for the whole organization (decision D56):
  admin   everything: tokens, webhooks, people, retention, limits, settings
  member  sites, goals, annotations, findings and search connections
  viewer  read only
"invite" prints a one-time link (7 days). Checkend sends no email: give the
link to the person. The person opens it and registers a passkey. A role change
takes effect on the next request of the person; "remove" ends the person's
sessions at once and revokes the person's API tokens. The last admin stays.
An admin can do all of this. Admins and Members can list the people; a Viewer gets exit 5
(decision D69).


Examples:
  ce people invite ana@example.com --role member
  ce people role ana@example.com viewer
  ce people remove ana@example.com --yes


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -role string
      the role of the invite: admin, member or viewer
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -yes
      remove without a question

ce projects

Section titled “ce projects”

List projects, set the daily event limit (admin).

Usage: ce projects list
       ce projects limit <id> --daily-events <n> [--dry-run]


"limit" sets the most events that the project accepts in one UTC day. The
server refuses events over the limit before it writes them. 0 means no limit.


Example:
  ce projects limit prj_default --daily-events 1000000


Flags:
  -context string
      the context to use (see "ce context list")
  -daily-events int
      the daily event limit (0: no limit) (default -1)
  -dry-run
      show the change, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce query

Section titled “ce query”

Show page views, visitors, top pages and conversions of a site.

Usage: ce query <site> [--period 24h|7d|30d|365d] [--json]
       ce query <site> --series [--period 24h|7d|30d|365d] [--goal <goal id>] [--json]


Prints the page views, the visitors, the top pages and the top countries of one
site. --series prints the time series instead: one row for each hour (24h) or
each UTC day, with the conversions (of one goal with --goal). Exit code 4 means
that the period has no data yet.


Examples:
  ce query example.com --period 7d
  ce query example.com --series --period 30d


Flags:
  -context string
      the context to use (see "ce context list")
  -goal string
      --series: the conversions of this goal ID only
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -period string
      the period: 24h, 7d, 30d or 365d (default "30d")
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -series
      print the time series (GET /v1/timeseries)
  -site string
      the site domain (or give it as the first argument)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce report

Section titled “ce report”

Show, list and make reports, and manage the report schedules.

Usage: ce report [show] [<site>] [--project <id>] [--frequency daily|weekly|monthly] [--date YYYY-MM-DD] [--id <id>] [--format md]
       ce report list [<site>] [--project <id>] [--frequency <f>] [--limit <n>] [--before <id>]
       ce report run [<site>] [--project <id>] [--frequency <f>] [--time-zone <zone>] [--schedule <id>] [--dry-run]
       ce report schedules list
       ce report schedules add [<site>] [--project <id>] --frequency <f> [--weekday <day>] [--hour <0-23>] [--time-zone <zone>] [--dry-run]
       ce report schedules set <id> [--frequency <f>] [--weekday <day>] [--hour <0-23>] [--time-zone <zone>] [--dry-run]
       ce report schedules delete <id> [--yes] [--dry-run]


A report is the numbers of one window in whole days of a time zone, against
the window before (with the significance tests), the top pages, sources and
channels, the goals, the revenue for each currency, the web vitals, the search
totals, the findings opened and closed, the outcomes and the annotations.
"show" prints the newest report (of a site, a project, a frequency, a date),
or one --id. --format md prints it as Markdown to paste; on a pipe the JSON
has the text in "markdown". "run" makes a report now of the newest complete
window: daily is yesterday, weekly the 7 days before today, monthly the
month before. A schedule makes a report daily, weekly on a weekday or monthly
on the first day, at a local hour, and sends the webhook report.ready.
Admins and Members manage schedules. Checkend sends no email.


Examples:
  ce report show example.com
  ce report show --project prj_default --frequency monthly --format md | jq -r .markdown
  ce report run example.com --frequency weekly --time-zone Europe/Berlin
  ce report schedules add example.com --frequency weekly --weekday monday --hour 7 --time-zone Europe/Berlin


Flags:
  -before string
      list: only reports older than this report ID (the next page)
  -context string
      the context to use (see "ce context list")
  -date string
      show: a day in the window, YYYY-MM-DD
  -dry-run
      show the change, do not make it
  -format string
      show: md prints the report as Markdown
  -frequency string
      daily, weekly or monthly
  -hour int
      schedules: the local hour, 0 to 23 (default 6)
  -id string
      show: a report ID
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      list: the most reports, 1 to 100 (default 20)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -project string
      a project ID: the project reports (all sites)
  -schedule string
      run: use the site, frequency and time zone of a schedule
  -time-zone string
      run, schedules: an IANA time zone, for example Europe/Berlin (default UTC)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -weekday string
      schedules: the day of a weekly report, monday to sunday
  -yes
      delete without a question

ce retention

Section titled “ce retention”

Show or set the raw-data retention of each module (admin).

Usage: ce retention
       ce retention set <module> --months <n> [--dry-run]


Checkend keeps the raw events of each module for a number of months (default
24, decision D26). The nightly retention job deletes the older months as file
deletes. The daily rollups and the search rows stay permanently, so the
numbers of old days stay; a visitor then counts one time on each day of a
deleted month. Admin only. The modules: analytics.


Examples:
  ce retention
  ce retention set analytics --months 18 --dry-run


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -months int
      set: the months of raw events to keep (1 to 120)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
Section titled “ce search”

Show Search Console and Bing rows; connect, check, sync and disconnect the sources.

Usage: ce search <site> [--period 7d|28d|90d|365d] [--by query|page] [--position 8-20]
                        [--source google|bing|all] [--query <text>] [--page <text>] [--limit 50]
       ce search connect <site> (--google | --bing --api-key-stdin) [--property <property>]
       ce search status <site>
       ce search disconnect <site> google|bing [--yes] [--dry-run]
       ce search sync <site>


Shows the Search Console and Bing rows of a site: clicks, impressions, CTR and the
average position, by query or by page. Page rows also have the Checkend page views,
visitors, page views from Organic Search and conversions of the same days, and the
current title. Search data is 2 to 3 days late: the period ends at the newest
search date. --position 8-20 shows the striking-distance rows. Exit code 4 means
that the site has no search data yet.


connect --google prints a consent page URL: open it in a browser as a person with
access to the property. The server needs a Google OAuth client of your own Google
Cloud project (checkend serve --google-client-id). connect --bing reads the API key
from stdin (Bing Webmaster Tools, Settings, API Access). The server stores the
token or the key encrypted. disconnect deletes them; the synced rows stay.


Examples:
  ce search example.com --period 28d --by query --position 8-20
  ce search example.com --by page
  ce search connect example.com --google --property sc-domain:example.com
  echo "$BING_KEY" | ce search connect example.com --bing --api-key-stdin


Flags:
  -api-key-stdin
      connect --bing: read the API key from stdin
  -bing
      connect: Bing Webmaster Tools (API key)
  -by string
      query (default) or page
  -context string
      the context to use (see "ce context list")
  -dry-run
      disconnect: show the change, do not make it
  -google
      connect: Search Console (OAuth consent page)
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      the most rows (default 50, at most 500)
  -page string
      keep rows whose page URL contains this text
  -period string
      7d, 28d (default), 90d or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -position string
      keep rows with an average position in this range, for example 8-20
  -property string
      connect: sc-domain:example.com or https://example.com/ (default: sc-domain:<site>, or https://<site>/ for bing)
  -query string
      keep rows whose query contains this text
  -source string
      google, bing or all (default)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -yes
      disconnect: do not ask

ce setup

Section titled “ce setup”

Make the first admin with the setup token, and log in.

Usage: ce setup <url> --email <email> --setup-token <token> [--name <context>]


Makes the first admin of a new server with the one-time setup token that the
server printed at its first start. Then it stores the new admin token as "ce
login" does: in the OS keychain, or in the credentials file when no keychain
works.


Example:
  ce setup https://checkend.example.com --email admin@example.com --setup-token cesetup_...


Flags:
  -email string
      the email address of the first admin (required)
  -name string
      the context name (default: the server host)
  -setup-token string
      the setup token from the server output (required)

ce sites

Section titled “ce sites”

List, add, change, delete and verify sites.

Usage: ce sites list [--project <id>]
       ce sites add <domain> [--privacy strict|standard|extended] [--project <id>] [--dry-run]
       ce sites set <domain> [--privacy strict|standard|extended] [--outcome-mde <percent>] [--dry-run]
       ce sites delete <domain> [--yes] [--dry-run]
       ce sites prompt <domain> [--dry-run]
       ce sites verify <domain> [--wait 2m] [--send-test]


"add" prints the script tag and the install prompt for a coding agent.
"set --outcome-mde" sets the outcome sensitivity of the site (admin): the
smallest change, in percent (5 to 50, default 10), that an outcome test must
find with 80 % power. A larger value needs less data, but misses small
changes. It applies to new outcomes; "ce findings remeasure" uses it too.
"prompt" makes a new install prompt with a new install token (24 hours).
The install token can only run "verify" for its site.
"verify" waits for the first page view of the site, and exits with 0 when
it arrives, or 4 when it does not. --send-test first sends one test event
("Checkend install test"), to check that the server takes events.


Examples:
  ce sites add example.com
  ce sites prompt example.com --plain          # only the prompt text
  ce sites prompt example.com | jq -r .prompt | pbcopy
  CHECKEND_TOKEN=ce_inst_... ce sites verify example.com --wait 5m


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -every duration
      verify: the time between two checks (default 2s)
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -outcome-mde string
      set: the outcome sensitivity in percent, 5 to 50 (admin)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -privacy string
      the privacy mode: strict, standard (default) or extended
  -project string
      the project ID (add: default project; list: all projects)
  -send-test
      verify: send one test event first
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -wait duration
      verify: how long to wait for the first event (default 2m0s)
  -yes
      delete without a question

ce tokens

Section titled “ce tokens”

List, create and revoke API tokens (admin; each person: own tokens).

Usage: ce tokens list
       ce tokens create --name <name> --scope <scope> [--scope <scope>...] [--dry-run]
       ce tokens revoke <id> [--dry-run]


Scopes: admin, read:*, write:*, read:<project>, write:<project>. Write includes
read. Give agents read-only tokens. "create" prints the secret one time.
An admin sees and revokes all tokens. A member or a viewer (D56) sees, makes and
revokes only the own tokens, with scopes inside the role (member: write:*,
viewer: read:*). A role change revokes the own tokens outside the new role.


Example:
  ce tokens create --name "weekly agent" --scope read:*


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -name string
      the token name
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -scope value
      a scope (repeat the flag for more)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce vitals

Section titled “ce vitals”

Show the web vitals (p75 of LCP, INP, CLS, TTFB) of a site and its pages.

Usage: ce vitals <site> [--period 24h|7d|30d|365d] [--path <path>] [--limit 20]


Shows the web vitals from real visitors: the 75th percentile (p75) of LCP, INP,
CLS and TTFB for the site and its top pages, with n and the web.dev rating
(good, needs_improvement, poor). The tracking script sends one report for each
page load. The numbers are not tested for significance. Exit code 4 means that
the period has no reports yet.


Examples:
  ce vitals example.com --period 7d
  ce vitals example.com --path /pricing --json


Flags:
  -context string
      the context to use (see "ce context list")
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -limit int
      the most pages (default 20)
  -path string
      one page path, for example /pricing
  -period string
      24h, 7d, 30d (default) or 365d
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)

ce webhooks

Section titled “ce webhooks”

Add, list, delete and test webhooks (admin).

Usage: ce webhooks add <url> [--event <event>]... [--dry-run]
       ce webhooks list
       ce webhooks delete <id> [--yes] [--dry-run]
       ce webhooks test <id>
       ce webhooks deliveries <id>


A webhook gets a signed POST request for each event: finding.created, finding.updated, annotation.created, disk.pressure, report.ready
(default: all). The body has the brief of the site; report.ready has the report. Check the Checkend-Signature header: HMAC-SHA256 with the secret over
"<t>.<body>". "add" shows the secret one time. The server refuses loopback,
private and link-local URLs unless it runs with --webhook-allow-private.
Admin only.


Examples:
  ce webhooks add https://agents.example.com/checkend --event finding.created
  ce webhooks test wh_0192...


Flags:
  -context string
      the context to use (see "ce context list")
  -dry-run
      show the change, do not make it
  -event value
      add: an event (repeat the flag for more)
  -json
      print JSON, also for errors (default when stdout is not a terminal)
  -plain
      Quiet output: plain columns (also env CHECKEND_PLAIN=1)
  -url string
      the server URL (default: the current context, or env CHECKEND_URL)
  -yes
      delete without a question

ce version

Section titled “ce version”

Show the version.

{
  "version": "dev"
}