CLI

Clics skills help AI agents use the CLI to manage projects, goals, funnels, sessions, and query privacy-friendly analytics from the terminal.

Clics skills are an easy way for AI agents such as Claude Code, Antigravity, and OpenCode to use Clics through the CLI.

Query analytics, manage projects, goals, funnels, and sessions directly from the terminal. The Clics CLI works standalone or with the Agent Skills that coding agents can discover and use automatically.

Prefer MCP when your agent already has the clics MCP server connected. Use the CLI when MCP is unavailable, for scripts and CI, or for manual verification.

Installation

For AI agents, install the Clics skill first:

npx skills add P-Essonam/clicsdev --skill clics

You can also install the Clics CLI globally with npm:

npm install -g @clicsdev/cli

Or run without a global install:

npx @clicsdev/cli --help

Authentication

Before using the CLI, authenticate with a Clics API key from Settings → API keys in the dashboard.

Login

# Save your API key locally (stored in ~/.config/clics/)
clics init --api-key YOUR_API_KEY

Re-run clics init anytime to rotate the key.

Logout

# Clear stored credentials
clics logout

Commands

All successful commands print a single JSON document on stdout. Errors go to stderr with a non-zero exit code.

Projects

Manage Clics projects from the terminal.

# 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

# Delete a project
clics projects delete <project-id>

Available options:

Goals

Create page or event goals for a project. env_id is production or development (default: production).

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

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

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

# Update a goal
clics goals update <goal-id> \
  --goal-type page \
  --display-name "Signup" \
  --page-path /signup

# Delete a goal
clics goals delete <goal-id>

Available options:

Funnels

List, get, and delete use flags. Create and update take a JSON body 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>

# Create a funnel from a JSON file
clics funnels create <project-id> --body @funnel.json

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

# Delete a funnel
clics funnels delete <funnel-id>

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 create body: production or development. Update bodies omit env_id.

Available options:

Sessions

List visitor sessions, fetch session details, and read the event timeline.

# 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> --cursor "<cursor>"

# Get session details
clics sessions get <project-id> <session-id>
clics sessions get <project-id> <session-id> --date-range last30days

# List session events
clics sessions events <project-id> <session-id>
clics sessions events <project-id> <session-id> --domain localhost

Period presets match clics query (last24h, last7days, …, allTime). Detail and events default to allTime when no range is set. Use --domain localhost for development traffic only.

Available options:

Query

Query analytics stats for a project. --metrics and --date-range are required unless you pass --file.

# Basic KPI query
clics query <project-id> \
  --metrics visitors pageviews bounce_rate \
  --date-range last30days

# With previous period comparison and totals
clics query <project-id> \
  --metrics visitors pageviews bounce_rate \
  --date-range last30days \
  --previous-period \
  --total-rows

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

# 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 from 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.

Available options:

Allowed metrics: visitors · visits · pageviews · bounce_rate · visit_duration · views_per_visit · conversion_rate · events

Allowed date ranges: 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

Global options

These options are available for all commands:

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

Output handling

The CLI outputs JSON to stdout by default, so you can pipe or redirect:

# Extract project IDs
clics projects list | jq '.projects[].id'

# Save query results
clics query <project-id> --metrics visitors --date-range last7days > visitors.json

# Pretty-print with jq
clics projects get <project-id> | jq .

Examples

Quick project check

clics projects list
clics projects get <project-id>

Create a signup goal

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

Weekly traffic snapshot

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

Top countries

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

Research workflow with an agent

With the Clics skill installed, ask your agent:

“Use Clics to list my projects, then show visitors for the last 7 days on the main site.”

The agent prefers MCP tools when connected, and falls back to the CLI when needed.

Skills and MCP

The Clics skill teaches agents when to choose MCP vs CLI, how to authenticate, and the command/tool reference for projects, goals, funnels, sessions, and stats.

Troubleshooting

Links

• Agent Skills
• Dashboard
• MCP setup
• API reference
• npm: @clicsdev/cli