@tsuga/cli

Command-line interface for managing Tsuga resources.

Installation

npm install -g @tsuga/cli

tsuga --help

Authentication

Before authenticating, generate an Operation API key from your Tsuga account settings.

The recommended way to authenticate is to save your Operation API key once:

tsuga auth <operation-api-key>

This writes your operation-api-key to ~/.config/tsuga/config.json. Alternatively, set credentials per-session without saving:

# Environment variable
export TSUGA_OPERATION_API_KEY=<operation-api-key>

# CLI flag (highest priority)
tsuga --operation-api-key <operation-api-key> dashboards list

Priority order: --operation-api-key flag → TSUGA_OPERATION_API_KEY env var → saved config.

Configuration

Show current configuration:

tsuga config

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:

tsuga defaults set from -1h
tsuga defaults set query 'level:ERROR'

View all current defaults (custom overrides marked with *):

tsuga defaults

Reset custom defaults:

tsuga defaults reset

Usage

Most resources follow the same CRUD pattern:

tsuga <resource> list
tsuga <resource> get <id>
tsuga <resource> create -f payload.json
tsuga <resource> update <id> -f payload.json
tsuga <resource> delete <id>

Read-only resources (for example services) support only:

tsuga services list
tsuga services get <id>

You can also pass JSON inline with -d:

tsuga teams create -d '{"name": "Platform", "visibility": "public"}'

Available resources

dashboards, ingestion-api-keys, monitors, notification-rules, notification-silences, retention-policies, routes, services, 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:

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:

tsuga monitors create --generate-skeleton > monitor.json
# edit monitor.json
tsuga monitors create -f monitor.json

Examples

# 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

# Get a specific service
tsuga services get abc-123

# 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

tsuga logs search --from -1h --query 'level:ERROR'
tsuga logs search --from 1704067200 --to 1704153600 --query 'service:api'

Search traces

tsuga traces search --from -30m --query 'span_name:GET'

Metrics

# 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:

tsuga aggregation scalar -f query.json
tsuga aggregation timeseries -f query.json

Use --generate-skeleton to get a template:

tsuga aggregation scalar --generate-skeleton > query.json

Tips

Output is always JSON, so you can pipe to jq:

tsuga dashboards list | jq '.[].name'
tsuga monitors list | jq '.[] | select(.priority == 1)'

Read from stdin with -f -:

echo '{"name": "My Team"}' | tsuga teams create -f -