@tailglow/cli

tglow is the Tailglow command line. Every command is generated from the API's own routes and validations, so the CLI, the docs site, llms.txt and the in-product AI assistant all describe the same API by construction.

npm install -g @tailglow/cli
tglow config set api_key tg_api_...
tglow projects list

Node 18.3 or newer. bun add -g and pnpm add -g work the same way.

Prefer a shorter name? Alias it rather than installing over one:

alias tg=tglow

Shape

tglow <resource> <command> [flags]

Run tglow for the resources, tglow <resource> for its commands, and tglow <resource> <command> --help for the flags, their types, allowed values and requiredness.

tglow metrics list --project prj_x
tglow metrics create --project prj_x --name "API Latency" --view-id view_x
tglow metrics delete --project prj_x --metric-id met_x

Field names are snake_case on the wire and kebab-case on the command line: time_window_minutes becomes --time-window-minutes. Object and array fields take JSON:

tglow views create-join --project prj_x --joins '[{"view_id":"view_b","on":"user_id"}]'

Credentials

Authentication is an API key, created in the dashboard under Team settings. Precedence is flag, then environment, then stored config:

tglow projects list --api-key tg_api_...     # this call only
TAILGLOW_API_KEY=tg_api_... tglow projects list
tglow config set api_key tg_api_...          # ~/.tailglow/config.json, mode 0600

A stored key is never printed back, by config get or anything else.

tglow config also stores a default project and team, which is what lets tglow metrics list work without repeating the project on every call. Those two are the only defaults: every other id has to be named on the command line, so nothing in your environment can quietly become the target of a delete.

Output

Human-readable tables in a terminal, JSON everywhere else. --json forces JSON; a pipe implies it, so tglow projects list | jq needs no flag. Failures go to stderr and follow the same mode, so a pipeline reading stdout never has to tell a result apart from an explanation of why there is none.

JSON is the API's response verbatim, envelope included, so the cursors and the message travel with the rows: read .data for the results and .pagination.next_cursor to continue.

tglow projects list --json | jq '.data[].name'

Lists

List commands paginate. --all follows the cursor, up to --max results (10,000 by default):

tglow metrics list --project prj_x --all --max 500

The cap is a guardrail, not a ceiling: records and collection documents are unbounded, so an uncapped follow would pull millions of rows into a terminal. A run that stops early always reports the cursor to resume from, printed as the whole command you typed plus --after. Under --json, --all returns { data, truncated, next_cursor } so a caller can continue on its own.

--all owns paging, so it does not combine with --limit or --before. Use --max for the total, and --limit on its own when you want a single page.

Deletes

A delete asks for confirmation in a terminal. --yes skips the prompt, and a non-interactive run proceeds without one, so scripts and agents are not blocked on a question they cannot answer.

Development

bun run tglow <resource> <command>   # run from source, without installing
bun run test:cli                     # unit tests, no network
bun run build:llms                   # regenerate src/commands.generated.js

src/commands.generated.js is written by scripts/build/llms.build.js and is never edited by hand. Adding a route to the API adds its command here with no change to this package.