CLI Commands

Tell’s CLI covers server management, analytics queries, live streaming, AI tools, and setup. Run tell <command> --help for details on any command.

Global flags

These flags work with any command:

Flag	Description
`--config <path>`	Path to config file
`--log-level <level>`	Log level: trace, debug, info, warn, error

Server

`tell run`

Start the Tell server. Loads config, binds sources, creates sinks, and runs until interrupted.

tell run
tell run --config configs/prod.toml

With no config file, starts with defaults: TCP source on port 50000, stdout sink. Checks all ports at startup and reports conflicts. Handles SIGHUP to hot-reload API keys without restart.

`tell status`

Check server health, uptime, and pipeline metrics.

tell status                    # health check
tell status --metrics          # detailed pipeline stats
tell status --watch            # live refresh every second
tell status --json             # JSON output
tell status --endpoint http://10.0.0.5:3000

Flag	Default	Description
`--metrics`	off	Show per-source and per-sink stats
`--watch`	off	Refresh every second with rate calculations
`--json`	off	Output as JSON
`--endpoint`	`http://127.0.0.1:3000`	API server URL

Analytics

`tell metrics`

Query DAU, MAU, sessions, stickiness, events, and logs from the command line. Uses the [query] config section for the backend (ClickHouse or local Arrow IPC).

tell metrics dau --range 30d
tell metrics wau --range 30d --breakdown device_type
tell metrics mau --range 90d --format json
tell metrics sessions --range 30d
tell metrics stickiness-daily --range 30d
tell metrics events --range 7d --name page_view
tell metrics events-top --range 7d --limit 10
tell metrics logs --range 7d --level error
tell metrics logs-top --range 7d
tell metrics drill-down users --range 7d --limit 100

Subcommands:

Subcommand	Description
`dau`	Daily active users
`wau`	Weekly active users
`mau`	Monthly active users
`sessions`	Total session count
`sessions-unique`	Distinct session IDs
`stickiness-daily`	DAU/MAU ratio
`stickiness-weekly`	WAU/MAU ratio
`events`	Event count over time (filter with `--name`)
`events-top`	Top events by count (limit with `--limit`)
`logs`	Log volume over time (filter with `--level`)
`logs-top`	Top logs by count
`drill-down`	Raw data: `users`, `events`, `logs`, `sessions`

Common flags:

Flag	Default	Description
`--range`	`30d`	Time range: `7d`, `30d`, `90d`, `today`, `ytd`, or `YYYY-MM-DD,YYYY-MM-DD`
`--granularity`	`daily`	`minute`, `hourly`, `daily`, `weekly`, `monthly`
`--breakdown`	—	Dimension: `device_type`, `country`, `os`, etc.
`--compare`	—	`previous` (prior period) or `yoy` (year-over-year)
`--format`	`table`	`table`, `json`, `csv`
`--workspace`	`1`	Workspace ID

`tell query`

Execute SQL queries against ClickHouse or local Arrow IPC files (Polars backend).

tell query "SELECT event_name, COUNT(*) FROM events GROUP BY event_name"
tell query "SELECT * FROM logs WHERE level = 'error' LIMIT 20" --format json
tell query "SELECT * FROM events LIMIT 10" --format csv

Flag	Default	Description
`--format`	`table`	`table`, `json`, `csv`
`--config`	—	Config file path (uses `[query]` section)

The backend is resolved from your config: reference a sink by name (query.sink = "clickhouse") or set inline connection details. Falls back to local Arrow IPC files in arrow/.

Live streaming

`tell tail`

Stream live data from a running Tell server. Connects via Unix socket to the tap server.

tell tail                                         # all data
tell tail --type event                            # events only
tell tail --type log --level error                # error logs
tell tail --workspace 1 --source tcp_main         # filter by source
tell tail --event "page_*" --output json          # glob filter, JSON output
tell tail --match "timeout|error" --output compact
tell tail --sample 0.01 --rate-limit 100          # 1% sample, max 100/s
tell tail --last 50                               # replay last 50 batches

Server-side filters (applied before data leaves the server):

Flag	Description
`--workspace <ID>`	Filter by workspace (repeatable)
`--source <NAME>`	Filter by source ID (repeatable)
`--type <TYPE>`	`event`, `log`, `syslog`, `metric`, `trace` (repeatable)
`--sample <RATE>`	Sample rate 0.0–1.0 (e.g. `0.01` = 1%)
`--rate-limit <N>`	Max batches per second
`--last <N>`	Replay last N batches on connect

Client-side content filters (applied after decoding):

Flag	Description
`--event <PATTERN>`	Event name glob (repeatable)
`--level <LEVEL>`	Log level: `error`, `warning`, `info`, `debug`, `trace` (repeatable)
`--match <REGEX>`	Regex pattern matching any string field

Output:

Flag	Default	Description
`--output`	`text`	`text`, `json`, `compact`, `raw`
`--no-color`	off	Disable colored output
`--verbose`	off	Show debug info
`--quiet`	off	Suppress connection messages
`--demo`	—	Print sample output to test colors (no connection)

AI tools

`tell ask`

Ask the LLM assistant a question about your analytics data. Streams the response to stdout; tool calls print to stderr.

tell ask "why did DAU drop last Tuesday?"
tell ask --workspace 2 "which users are most likely to churn?"
echo "summarize my boards" | tell ask

Requires [llm] enabled = true in config and tell login for authentication. The question can also be piped via stdin.

`tell mcp`

Start the MCP server over stdio for integration with Claude Desktop, Cursor, Zed, and other MCP clients.

tell mcp
tell mcp --config configs/prod.toml
tell mcp --api-key <key>

The API key is resolved from: --api-key flag, TELL_API_KEY environment variable, or stored auth token (~/.tell/auth.json).

`tell skill`

Manage custom LLM skills — markdown files that extend the system prompt.

tell skill list                   # show built-in + custom skills
tell skill add path/to/skill.md   # add a custom skill
tell skill remove my-skill        # remove by name

Custom skills are stored in ~/.tell/skills/.

Setup

`tell apikeys`

Manage TCP API keys for SDK ingestion.

tell apikeys                   # list all keys
tell apikeys new mobile-prod   # create a new key
tell apikeys new backend --workspace 2
tell apikeys show mobile-prod  # show full key
tell apikeys delete old-key    # delete (with confirmation)
tell apikeys delete old-key -y # skip confirmation

Authenticate with the Tell API. Credentials are stored securely.

tell login
tell logout

`tell license`

Manage your Tell license key.

tell license show                  # current status and tier
tell license activate <KEY>        # activate a license
tell license deactivate            # remove license (reverts to free tier)

`tell setup-db`

Create ClickHouse workspace — database, tables, users, and config.

tell setup-db init <workspace>

Advanced

`tell test`

Send sample events and logs to verify the pipeline is working.

tell test                                        # 3 events + 3 logs to localhost
tell test --server 192.168.1.100:50000           # custom server
tell test --events 10 --logs 5                   # custom counts
tell test --api-key 00010203040506070809...       # custom API key (32 hex chars)

`tell read`

Decode disk binary files written by the disk sink.

tell read /data/disk/1/2025-01-15/events.bin
tell read /data/disk/1/2025-01-15/

`tell telemetry`

Show what telemetry data Tell would send. For transparency — inspect the exact payload before enabling.

tell telemetry show
tell telemetry show --json

CLI

AI Integration

Running Tell

CLI Commands

Global flags

Server

`tell run`

`tell status`

Analytics

`tell metrics`

`tell query`

Live streaming

`tell tail`

AI tools

`tell ask`

`tell mcp`

`tell skill`

Setup

`tell apikeys`

`tell license`

`tell setup-db`

Advanced

`tell test`

`tell read`

`tell telemetry`

CLI

AI Integration

Running Tell

​Global flags

​Server

​tell run

​tell status

​Analytics

​tell metrics

​tell query

​Live streaming

​tell tail

​AI tools

​tell ask

​tell mcp

​tell skill

​Setup

​tell apikeys

​tell login / tell logout

​tell license

​tell setup-db

​Advanced

​tell test

​tell read

​tell telemetry

Global flags

Server

`tell run`

`tell status`

Analytics

`tell metrics`

`tell query`

Live streaming

`tell tail`

AI tools

`tell ask`

`tell mcp`

`tell skill`

Setup

`tell apikeys`

`tell login` / `tell logout`

`tell license`

`tell setup-db`

Advanced

`tell test`

`tell read`

`tell telemetry`