@tsuga/cli 1.0.1

package/README.md

@@ -0,0 +1,216 @@
+# @tsuga/cli
+
+Command-line interface for managing Tsuga resources.
+
+## Installation
+
+```bash
+npm install -g @tsuga/cli
+```
+
+```bash
+tsuga --help
+```
+
+## Authentication
+
+Before authenticating, generate an API token from your [Tsuga account settings](https://app.tsuga.com/settings/api-keys?operation=true).
+
+The recommended way to authenticate is to save your token once:
+
+```bash
+tsuga auth <token>
+```
+
+This writes your token to `~/.config/tsuga/config.json`. You can also optionally save an API URL override:
+
+```bash
+tsuga auth <token> --url https://api.tsuga-staging.com
+```
+
+Alternatively, set credentials per-session without saving:
+
+```bash
+# Environment variable
+export TSUGA_OPERATION_API_KEY=<token>
+
+# CLI flag (highest priority)
+tsuga --api-token <token> dashboards list
+```
+
+Priority order: `--api-token` flag → `TSUGA_OPERATION_API_KEY` env var → saved config.
+
+## Configuration
+
+Show current configuration:
+
+```bash
+tsuga config
+```
+
+Override the API URL:
+
+```bash
+tsuga --api-url https://api.tsuga-staging.com dashboards list
+# or
+export TSUGA_API_URL=https://api.tsuga-staging.com
+```
+
+## Defaults
+
+Telemetry commands have built-in defaults so you can omit common flags:
+
+| Flag            | Default |
+| --------------- | ------- |
+| `--from`        | `-30m`  |
+| `--to`          | `now`   |
+| `--query`       | `*`     |
+| `--max-results` | `100`   |
+
+Override defaults for your session:
+
+```bash
+tsuga defaults set from -1h
+tsuga defaults set query 'level:ERROR'
+```
+
+View all current defaults (custom overrides marked with `*`):
+
+```bash
+tsuga defaults
+```
+
+Reset custom defaults:
+
+```bash
+tsuga defaults reset
+```
+
+## Usage
+
+All resources follow the same CRUD pattern:
+
+```bash
+tsuga <resource> list
+tsuga <resource> get <id>
+tsuga <resource> create -f payload.json
+tsuga <resource> update <id> -f payload.json
+tsuga <resource> delete <id>
+```
+
+You can also pass JSON inline with `-d`:
+
+```bash
+tsuga teams create -d '{"name": "Platform", "visibility": "public"}'
+```
+
+### Available resources
+
+`dashboards`, `ingestion-api-keys`, `monitors`, `notification-rules`, `notification-silences`, `retention-policies`, `routes`, `tag-policies`, `teams`
+
+> Note: `ingestion-api-keys` does not support `get <id>`.
+
+### Generating a request skeleton
+
+Any `create` or `update` command accepts `--generate-skeleton` to print a JSON template of the expected request body:
+
+```bash
+tsuga monitors create --generate-skeleton
+tsuga notification-rules update abc-123 --generate-skeleton
+```
+
+Pipe the output to a file, fill it in, then pass it back with `-f`:
+
+```bash
+tsuga monitors create --generate-skeleton > monitor.json
+# edit monitor.json
+tsuga monitors create -f monitor.json
+```
+
+### Examples
+
+```bash
+# List all monitors
+tsuga monitors list
+
+# Get a specific dashboard
+tsuga dashboards get abc-123
+
+# List dashboards filtered by owner
+tsuga dashboards list --owners team-1 team-2
+
+# Create a notification rule from a file
+tsuga notification-rules create -f rule.json
+
+# Update a route
+tsuga routes update abc-123 -d '{"name": "Updated route"}'
+
+# Delete a retention policy
+tsuga retention-policies delete abc-123
+```
+
+## Telemetry
+
+### Time formats
+
+`--from` and `--to` accept any of:
+
+| Format       | Example                      |
+| ------------ | ---------------------------- |
+| Relative     | `-30m`, `-1h`, `-7d`, `-30s` |
+| Now          | `now`                        |
+| Unix seconds | `1704067200`                 |
+| ISO 8601     | `2024-01-01T00:00:00Z`       |
+
+### Search logs
+
+```bash
+tsuga logs search --from -1h --query 'level:ERROR'
+tsuga logs search --from 1704067200 --to 1704153600 --query 'service:api'
+```
+
+### Search traces
+
+```bash
+tsuga traces search --from -30m --query 'span_name:GET'
+```
+
+### Metrics
+
+```bash
+# List all metrics
+tsuga metrics list --from -1h
+
+# Get a specific metric
+tsuga metrics get my.metric.name --from -1h
+```
+
+## Aggregation
+
+Run aggregation queries with a JSON body:
+
+```bash
+tsuga aggregation scalar -f query.json
+tsuga aggregation timeseries -f query.json
+```
+
+Use `--generate-skeleton` to get a template:
+
+```bash
+tsuga aggregation scalar --generate-skeleton > query.json
+```
+
+## Tips
+
+Output is always JSON, so you can pipe to `jq`:
+
+```bash
+tsuga dashboards list | jq '.[].name'
+tsuga monitors list | jq '.[] | select(.priority == 1)'
+```
+
+Read from stdin with `-f -`:
+
+```bash
+echo '{"name": "My Team"}' | tsuga teams create -f -
+```