@clicsdev/cli

v1.0.12

Published

22 days ago

Clics CLI — privacy-friendly, cookieless analytics

@clicsdev/cli

Privacy-friendly analytics from your terminal, made by Clics.

Command-line interface for cookie-free web analytics — manage projects, goals, funnels, sessions, AI crawlers, and query stats without a browser. Built for teams that want GDPR-friendly measurement, API access, and automation from scripts and CI.

All command output is JSON on stdout. Errors are printed on stderr with a non-zero exit code.

Install

npm install -g @clicsdev/cli

Or run without a global install:

npx @clicsdev/cli --help

Authenticate

Create an API key in the Clics dashboard, then save it locally:

clics init --api-key "<your-api-key>"

Re-run clics init anytime to rotate the key.

Logout

Clear stored credentials:

clics logout

Global options

clics --help
clics --version
clics help <command>

Projects

List projects

clics projects list
clics projects list --limit 20
clics projects list --cursor "<cursor>"

Get a project

clics projects get <project-id>

Create a project

clics projects create --name "My site" --website-url https://example.com
clics projects create --name "My site" --website-url https://example.com --allow-localhost

Update a project

clics projects update <project-id> --name "New name"
clics projects update <project-id> --website-url https://new.example.com
clics projects update <project-id> --allow-localhost
clics projects update <project-id> --no-allow-localhost

Delete a project

clics projects delete <project-id>

Goals

env_id is production or development (API default: production).

List goals

clics goals list <project-id>
clics goals list <project-id> --env-id development

Get a goal

clics goals get <goal-id>

Create a goal

Page goal:

clics goals create <project-id> --goal-type page --display-name "Signup page" --page-path /signup

Event goal:

clics goals create <project-id> --goal-type event --display-name "Purchase" --event-name purchase

Outbound link goal:

clics goals create <project-id> --goal-type outbound --display-name "Partner signup" --outbound-url https://partner.example.com/signup

Scroll-depth goal:

clics goals create <project-id> --goal-type scroll_depth --display-name "Read 75% of pricing" --page-path /pricing --scroll-depth-threshold 75

Goal rules are type-specific: page requires --page-path; event requires --event-name; outbound requires the exact --outbound-url; and scroll_depth requires both --page-path and a whole --scroll-depth-threshold from 1 to 100.

Optional environment:

clics goals create <project-id> --goal-type page --display-name "Home" --page-path / --env-id development

Get goal statistics

Returns dashboard-ready totals, period comparison, and time series for one goal. All period-based commands accept an IANA timezone and use UTC by default.

clics goals stats <goal-id> --date-range last30days
clics goals stats <goal-id> --start 2026-07-01 --end 2026-07-31 --timezone Europe/London
clics goals stats <goal-id> --domain app.example.com --ai-provider chatgpt

--ai-provider accepts chatgpt, claude, gemini, perplexity, or copilot.

Update a goal

clics goals update <goal-id> --goal-type page --display-name "Signup" --page-path /signup
clics goals update <goal-id> --goal-type event --display-name "Purchase" --event-name purchase
clics goals update <goal-id> --goal-type outbound --display-name "Partner signup" --outbound-url https://partner.example.com/signup
clics goals update <goal-id> --goal-type scroll_depth --display-name "Read 75%" --page-path /pricing --scroll-depth-threshold 75

Delete a goal

clics goals delete <goal-id>

Funnels

Simple list/get/delete use flags. Create/update take a JSON body (via --body inline or @file.json) because funnel steps are structured.

List funnels

clics funnels list <project-id>
clics funnels list <project-id> --env-id production --limit 20
clics funnels list <project-id> --cursor "<cursor>"

Get a funnel

clics funnels get <funnel-id>

Get funnel statistics

Returns dashboard-ready step counts, conversion, drop-off, and timing.

clics funnels stats <funnel-id> --date-range last30days
clics funnels stats <funnel-id> --start 2026-07-01 --end 2026-07-31 --timezone Europe/London
clics funnels stats <funnel-id> --domain app.example.com --ai-provider chatgpt

--ai-provider accepts chatgpt, claude, gemini, perplexity, or copilot.

Create a funnel

clics funnels create <project-id> --body @funnel.json

Example funnel.json:

{
  "name": "Signup funnel",
  "conversion_window": { "value": 7, "unit": "days" },
  "steps": [
    {
      "name": "Landing",
      "filters": [{ "filter_type": "page", "operator": "is", "values": ["/"] }]
    },
    {
      "name": "Signup",
      "filters": [
        { "filter_type": "page", "operator": "is", "values": ["/signup"] }
      ]
    }
  ]
}

Optional env_id in the body: production | development.

Update a funnel

Same shape as create, without env_id:

clics funnels update <funnel-id> --body @funnel-update.json

Delete a funnel

clics funnels delete <funnel-id>

Sessions

List session filter values

Get the values available for a Sessions filter in the selected analytics scope.

clics sessions filter-values <project-id> --field country --date-range last30days
clics sessions filter-values <project-id> --field referrer --domain app.example.com --timezone Europe/London --limit 100

Allowed fields: country · device · browser · os · page_entry · page_exit · referrer.

List sessions

clics sessions list <project-id>
clics sessions list <project-id> --date-range last7days --limit 20
clics sessions list <project-id> --domain example.com --date-range last30days
clics sessions list <project-id> --start 2026-07-01 --end 2026-07-15
clics sessions list <project-id> --date-range last30days --timezone Europe/London
clics sessions list <project-id> --cursor "<cursor>"

Get a session

clics sessions get <project-id> <session-id>
clics sessions get <project-id> <session-id> --date-range last30days
clics sessions get <project-id> <session-id> --timezone Europe/London

List session events

clics sessions events <project-id> <session-id>
clics sessions events <project-id> <session-id> --domain localhost
clics sessions events <project-id> <session-id> --timezone Europe/London

AI crawlers

AI crawler analytics always query production.

clics ai-crawlers <project-id>
clics ai-crawlers <project-id> --date-range last30days --timezone Europe/London
clics ai-crawlers <project-id> --category search_index
clics ai-crawlers <project-id> --provider OpenAI --crawler GPTBot --status 200
clics ai-crawlers <project-id> --provider OpenAI Anthropic
clics ai-crawlers <project-id> --provider OpenAI --provider-op is_not

--category accepts answer_fetch, search_index, or training. --provider and --crawler accept one or more enum values from the supported crawler registry. Filter operators accept is or is_not.

Providers: OpenAI, Anthropic, Perplexity, Google, Microsoft, Mistral, Amazon, DuckDuckGo, Apple, Moonshot AI, Common Crawl.

Crawlers: ChatGPT-User, OAI-SearchBot, GPTBot, Claude-User, Claude-SearchBot, ClaudeBot, Perplexity-User, PerplexityBot, Google-Agent, Google-GeminiNotebook, Google-NotebookLM, Google-Read-Aloud, Google-InspectionTool, Googlebot, GoogleOther, Google-CloudVertexBot, Bingbot, msnbot, MistralAI-User, MistralAI-Index, Amzn-User, Amzn-SearchBot, Amazonbot, DuckAssistBot, Applebot, Kimi-User, Kimi-SearchBot, KimiBot, CCBot.

Query analytics

--metrics and --date-range are required.

Date ranges

clics query <project-id> --metrics visitors --date-range last24h
clics query <project-id> --metrics visitors --date-range last7days
clics query <project-id> --metrics visitors --date-range last30days
clics query <project-id> --metrics visitors --date-range last3months
clics query <project-id> --metrics visitors --date-range last12months
clics query <project-id> --metrics visitors --date-range monthToDate
clics query <project-id> --metrics visitors --date-range quarterToDate
clics query <project-id> --metrics visitors --date-range yearToDate
clics query <project-id> --metrics visitors --date-range allTime

Basic KPI query

clics query <project-id> --metrics visitors pageviews bounce_rate --date-range last30days
clics query <project-id> --metrics visitors pageviews --date-range last30days --timezone Europe/London

With comparison / totals

clics query <project-id> --metrics visitors pageviews bounce_rate --date-range last30days --previous-period --total-rows

For a KPI query without --dimensions, --previous-period adds a comparison object to the JSON response:

{
  "comparison": {
    "previous_metric_values": { "visitors": 120, "pageviews": 340 },
    "change_percent": { "visitors": 12.5, "pageviews": -4.2 }
  }
}

comparison is omitted for breakdowns and time-series queries.

Domain filter

clics query <project-id> --metrics visitors --date-range last7days --domain example.com

Use --domain localhost for development traffic only.

Breakdown by dimension

clics query <project-id> --metrics visitors pageviews --date-range last30days --dimensions visit:country

Pagination

clics query <project-id> --metrics visitors --date-range last30days --dimensions visit:country --limit 50 --offset 0

Advanced query file

For filters, order_by, custom date ranges, or full control, use a JSON file:

clics query <project-id> --file query.json

Example query.json:

{
  "metrics": ["visitors", "pageviews", "bounce_rate"],
  "date_range": "last30days",
  "dimensions": ["visit:country"],
  "filters": [["is", "visit:country", ["US", "FR"]]],
  "order_by": [["visitors", "desc"]],
  "include": {
    "previous_period": true,
    "total_rows": true
  },
  "pagination": {
    "limit": 50,
    "offset": 0
  }
}

project_id in the file is overwritten by the CLI argument.

Use the optional timezone field in a query file to group custom ranges and time series in an IANA timezone. UTC is the default when it is omitted.

Allowed metrics

visitors · visits · pageviews · bounce_rate · visit_duration · views_per_visit · conversion_rate · events

KPI / time-series typically use: visitors, visits, pageviews, bounce_rate, visit_duration, views_per_visit.

Breakdown typically uses: visitors, pageviews, conversion_rate, events.

Allowed date ranges

Presets: last24h · last7days · last30days · last3months · last12months · monthToDate · quarterToDate · yearToDate · allTime

Custom ISO start/end pairs are supported via --file.

Allowed dimensions

event:page · event:hostname · event:name · event:outbound_url · visit:country · visit:device · visit:browser · visit:os · visit:referrer · referrer:ai_provider · visit:utm_source · visit:utm_medium · visit:utm_campaign · visit:utm_term · visit:utm_content · time · time:hour · time:day

Output and scripting

Every successful command prints a single JSON document:

clics projects list | jq '.projects[].id'

Troubleshooting

API key is required. Run clics init. — Run clics init --api-key "..."
401 / invalid key — Rotate or recreate the key, then re-run init
403 / UPGRADE_REQUIRED — Paid plan required for the API
Invalid metrics / date_range — Use values from the lists above
Funnel/query JSON errors — Prefer --body @file.json / --file file.json over inline JSON (especially on PowerShell)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@clicsdev/cli

Install

Authenticate

Logout

Global options

Projects

List projects

Get a project

Create a project

Update a project

Delete a project

Goals

List goals

Get a goal

Create a goal

Get goal statistics

Update a goal

Delete a goal

Funnels

List funnels

Get a funnel

Get funnel statistics

Create a funnel

Update a funnel

Delete a funnel

Sessions

List session filter values

List sessions

Get a session

List session events

AI crawlers

Query analytics

Date ranges

Basic KPI query

With comparison / totals

Domain filter

Breakdown by dimension

Pagination

Advanced query file

Allowed metrics

Allowed date ranges

Allowed dimensions

Output and scripting

Troubleshooting

Links