> ## Documentation Index > Fetch the complete documentation index at: https://docs.tell.rs/llms.txt > Use this file to discover all available pages before exploring further. # CLI Commands > Complete reference for all Tell CLI commands — server, metrics, tail, query, and more. Tell's CLI covers server management, analytics queries, live streaming, AI tools, and setup. Run `tell --help` for details on any command. ## Global flags These flags work with any command: | Flag | Description | | --------------------- | -------------------------------------------------------------- | | `--config ` | Path to config file | | `--data-dir ` | Root data directory (overrides config and `TELL_DATA_DIR` env) | | `--log-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. ```bash theme={null} 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](/running-tell/api-keys) without restart. ### `tell status` Check server health, uptime, and pipeline metrics. ```bash theme={null} 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 | ### `tell init` Generate a starter config file. ```bash theme={null} tell init # writes tell-config.toml tell init --output configs/prod.toml ``` ## 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). ```bash theme={null} 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` | | `saved` | Manage [saved metrics](/analytics/boards#saved-metrics) — `list`, `get`, `create`, `delete` | **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). ```bash theme={null} 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/`. ### `tell boards` Manage [boards](/analytics/boards) from the command line. ```bash theme={null} tell boards # list all boards tell boards list --pinned # pinned boards only tell boards create "Product Overview" tell boards create "Q1 Metrics" -d "Quarterly review dashboard" tell boards get # show board details tell boards delete # delete (with confirmation) tell boards pin # pin to top tell boards unpin tell boards share # create/show public link tell boards unshare # revoke public link ``` Add `--json` for machine-readable output. Add `--workspace` to target a specific workspace. ### `tell mark` Create timeline [marks](/analytics/boards#marks) to annotate charts with deploys, incidents, or launches. ```bash theme={null} tell mark "Shipped v2.1.0" tell mark "Payments down" -c incident --at 2025-06-15T23:47:00Z tell mark "Series A announced" -c news -d "Blog post went live" --source-ref https://blog.example.com tell mark --private "Testing hypothesis" tell mark list # last 90 days tell mark list --last 30d -c release tell mark delete ``` | Flag | Default | Description | | --------------- | --------- | -------------------------------- | | `--category` | `release` | `release`, `news`, or `incident` | | `--at` | now | ISO 8601 timestamp | | `--description` | — | Description text | | `--source-ref` | — | URL or reference | | `--private` | off | Visible only to you | ### `tell workspace` Manage [workspaces](/running-tell/workspaces) and members. ```bash theme={null} tell workspace # list your workspaces tell workspace create "My App" my-app tell workspace members # list members of current workspace tell workspace invite user@example.com --role editor ``` | Flag | Default | Description | | -------- | -------- | -------------------------------------------- | | `--role` | `viewer` | `viewer`, `editor`, or `admin` (for invites) | ## Live streaming ### `tell tail` Stream live data from a running Tell server. Connects via Unix socket to the tap server. ```bash theme={null} 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 ` | Filter by workspace (repeatable) | | `--source ` | Filter by source ID (repeatable) | | `--type ` | `event`, `log`, `syslog`, `metric`, `trace` (repeatable) | | `--sample ` | Sample rate 0.0–1.0 (e.g. `0.01` = 1%) | | `--rate-limit ` | Max batches per second | | `--last ` | Replay last N batches on connect | **Client-side content filters** (applied after decoding): | Flag | Description | | ------------------- | -------------------------------------------------------------------- | | `--event ` | Event name glob (repeatable) | | `--level ` | Log level: `error`, `warning`, `info`, `debug`, `trace` (repeatable) | | `--match ` | 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. ```bash theme={null} 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. ```bash theme={null} tell mcp tell mcp --config configs/prod.toml tell mcp --api-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. ```bash theme={null} 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. ```bash theme={null} 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 ``` ### `tell login` / `tell logout` Authenticate with the Tell API. Credentials are stored securely. ```bash theme={null} tell login tell logout ``` ### `tell license` Manage your Tell license key. ```bash theme={null} tell license show # current status and tier tell license activate # activate a license tell license deactivate # remove license (reverts to free tier) ``` ### `tell schema` Manage ClickHouse workspace schemas — create databases, tables, and users. ```bash theme={null} tell schema create # create workspace schema tell schema create --dry-run # preview SQL without executing tell schema check # verify workspace is set up tell schema destroy # remove all data (with confirmation) tell schema dump # print schema DDL to stdout ``` ## Plugins ### `tell plugin` Manage WASM [integrations](/tracking/integrations/overview) — install, update, and run plugins. ```bash theme={null} tell plugin list # registry + installed status tell plugin list --installed # locally installed only tell plugin search github # search the registry tell plugin info cloudflare # show plugin details tell plugin install cloudflare # install from registry tell plugin install ./my-plugin.wasm --name custom tell plugin update # update all plugins tell plugin update cloudflare # update specific plugin tell plugin remove cloudflare tell plugin pull cloudflare # pull data from plugin ``` ## Advanced ### `tell test` Send sample events and logs to verify the pipeline is working. ```bash theme={null} 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](/pipeline/sinks/disk). ```bash theme={null} 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. ```bash theme={null} tell telemetry show tell telemetry show --json ```