@tailglow/cli 0.2.0

package/README.md

@@ -0,0 +1,104 @@
+# @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.
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+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.
+
+```bash
+tglow projects list --json | jq '.data[].name'
+```
+
+## Lists
+
+List commands paginate. `--all` follows the cursor, up to `--max` results (10,000 by default):
+
+```bash
+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
+
+```bash
+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.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@tailglow/cli",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "The Tailglow command line. Every command is generated from the Tailglow API reference, so the CLI and the documentation can never describe different APIs.",
+  "bin": {
+    "tglow": "./src/index.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./commands": "./src/commands.generated.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tailglow-dev/monorepo.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "tailglow",
+    "cli",
+    "analytics",
+    "observability"
+  ],
+  "license": "ISC",
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6"
+  }
+}