CLI

The CLI is the fastest route into your data. Everything the dashboard and the digest show is available here, in formats you can pipe.

Installation

pip install clientlog-cli
clientlog login you@example.com

Credentials are stored in ~/.clientlog/auth.json.

Global options

--origin and --project scope almost every command, and they precede the subcommand:

clientlog --origin https://example.com --project myapp/home sessions list

Set them once in your environment instead:

export CLIENTLOG_ORIGIN=https://example.com
export CLIENTLOG_PROJECT=myapp/home

clientlog sessions list

Output formats

table is the default and is meant for reading. json and csv are for piping. markdown produces a table to paste into a document.

llm is worth knowing about: it renders sessions as a compact summary with aggregate statistics followed by one line per session, sized for pasting into a language model along with a question.

clientlog --format llm sessions list --limit 50 | pbcopy

SESSIONS SUMMARY (n=50)

Total Events: 412
Avg Duration: 94.2s
Avg Events/Session: 8.2

Top Countries: GB(29), US(12), DE(4)
Devices: desktop(38), mobile(11), tablet(1)

DETAILED SESSIONS:
[1782693098872-7xzwuxbzd] | 2026-08-31 14:02 | 142.4s | Bradford, GB | page_view.home -> scroll -> page_exit.home -> page_view.pricing

sessions

clientlog sessions list --limit 20
clientlog sessions get --sessions <id> [<id> ...]
clientlog sessions events --session-id <id>
clientlog sessions attributes --session-id <id>

list shows recent sessions with event counts, duration and tags. get fetches full detail for named sessions. events returns the ordered event list for one session, which is the view to reach for when debugging a specific user’s experience. attributes returns values extracted by attribution rules.

events

clientlog events list --limit 50 [--raw]
clientlog events names
clientlog events watch [--interval 5] [--session <id>] [--raw]

names lists every distinct action seen with its last-seen time. This is the instrumentation coverage check.

watch polls for new events and prints them as they arrive, which is what you want open in a second terminal while testing a change.

--raw returns events as received, without enrichment.

projects

clientlog projects list
clientlog projects overview --limit 1

overview returns the stored digest data on demand: traffic, sessions, bot ratio, devices, regions, tag distribution and transition insights for recent windows.

rules

clientlog rules list
clientlog rules get <rule_id>
clientlog rules create --rule-id <id> --tag <tag> --logic '<json>' \
                       [--description <text>] [--notification-target email]
clientlog rules update <rule_id> [--tag ...] [--logic ...] [--enabled ...]
clientlog rules delete <rule_id> [--yes]
clientlog rules test --rules-file rules.yaml --session-file session.json

For everyday work use plan and apply below; these are the individual operations underneath.

plan and apply

The rules workflow. Your YAML file is the source of truth, the database is deployed state, and these two commands manage the difference.

clog plan --file rules.yaml --origin https://example.com --project myapp/home

example.com/myapp/home
comparing rules.yaml against deployed rules

  ~ any_session         [modified]
      notification_target: null -> "email"

  = engaged             [unchanged]
  + pricing_visitor     [new - will be created]
  - old_rule            [removed - will be deleted]

summary: 1 modified, 1 added, 1 removed, 1 unchanged

clog apply --file rules.yaml --origin https://example.com --project myapp/home \
           [--dry-run] [--auto-approve]

Exit codes: 0 no differences, 1 differences found, 2 validation error, 3 auth or API error. --strict on plan treats any drift as failure, for pipelines where deployed state must match the file exactly.

Full workflow in rules.

trigger

clientlog trigger aggregation  [--hours 24]
clientlog trigger notification [--method email] [--hours 1]
clientlog trigger transitions  [--hours 24] [--min-sessions 2] [--min-probability 0.01]
clientlog trigger classifier   --session <id> [<id> ...]

Jobs normally run on a schedule. Trigger them when you want a window processed now: after installing the client, after changing rules, or when reprocessing historical sessions against a new rule.

status

clientlog status health [--limit 1]

Pipeline health: ingestion rate, enrichment lag, per-service status and any recorded issues.

Workflows

After installing the client.

clientlog events names
clientlog trigger aggregation --hours 1
clientlog sessions list --limit 5

Debugging one visitor’s experience.

clientlog sessions list --limit 50
clientlog sessions events --session-id 1782693098872-7xzwuxbzd --format json

Reprocessing after a rule change.

clog apply --file rules.yaml
clientlog sessions list --limit 100 --format json \
  | jq -r '.[].session' \
  | xargs clientlog trigger classifier --session

Exporting a month for analysis.

clientlog --format csv sessions list --limit 1000 > sessions.csv

Watching a deployment.

clientlog events watch --interval 3