> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Use the Squasher CLI for agent-friendly project discovery, telemetry queries, integration setup, and workflow automation.

Use the Squasher CLI when a local script or coding agent needs an auditable terminal workflow. Run `squasher <command> --help` for exact flags in your installed version.

## Auth and project scope

```bash theme={null}
squasher login
squasher login --device-code
squasher login --key "$SQUASHER_API_KEY"
squasher logout
squasher config
squasher profiles list
squasher profiles create production --project <project_id> --api-key-env SQUASHER_PRODUCTION_API_KEY
squasher profiles use production
squasher projects list
squasher services list
squasher projects get <project-id>
squasher projects use <project-id>
```

`projects` and `services` address the same service-project API. Most project-scoped commands accept `--project <project_id>`, `SQUASHER_PROJECT_ID=<project_id>`, or the active project saved with `squasher projects use <project_id>`. Use `--profile <name>` to run a command against a different local profile without switching the default. `--api-key-env <variable>` stores only an environment-variable reference for that profile; the selected variable wins over the shared `SQUASHER_API_KEY`, and a missing value fails closed instead of falling back to another profile's key. Profile updates preserve omitted fields; use the explicit `--clear-project`, `--clear-api-url`, `--clear-app-url`, or `--clear-api-key-env` flag to remove one.

## Observability

```bash theme={null}
squasher query-guide get --project <project_id>
squasher observe summary --project <project_id>
squasher errors list --project <project_id> --status unresolved --limit 10
squasher errors get --project <project_id> <error_group_id>
squasher logs search --project <project_id> --query "timeout" --limit 50
squasher logs query "level:error service:api" --since 1h
squasher logs insights --project <project_id> --service <service_name> --since 1h \
  --dimension gen_ai.request.model --dimension cloud.region --dimension http.route
squasher logs tail --level error --duration 5m
squasher logs forward --file app.log --public-key "$SQUASHER_PUBLIC_KEY"
squasher events search --project <project_id> --limit 25
squasher traces operations --project <project_id>
squasher traces list --project <project_id> --service-name api --status error
squasher traces get --project <project_id> <trace_id>
squasher metrics inspect --project <project_id> --metric-name http.server.duration --metric-type hist
squasher vitals summary --project <project_id>
squasher vitals breakdown --project <project_id> --metric LCP --dimension page_path --percentile p75 --period 24h
squasher vitals breakdown --project <project_id> --metric INP --dimension country --filter page_path=/pricing
```

Use `query-guide` first when the next surface is unclear. Use `observe summary`, `metrics inspect`, `dashboards inspect-query`, and `replays inspect` when an agent needs a compact explanation before raw rows.
For frontend performance checks, use `vitals summary` first, then `vitals breakdown` to segment Web Vitals by page path, country, region, city, browser, device type, campaign, user, trace, or metadata filters.
The log-insights API requires `from` to be no later than `to` and limits the resolved window to 30 days. Invalid or oversized windows return HTTP `400`; keep CLI or scripted investigations inside that bound.

## Conversational debugging

```bash theme={null}
squasher ask "why is checkout timing out?" --wait
squasher threads create --title "Checkout investigation"
squasher threads list
squasher threads list --incident INC-123
squasher threads search "checkout timeout"
squasher messages send "keep investigating the database pool" --thread <thread_id>
```

Use `--wait` when you want the terminal to stream the assistant response. Without `--wait`, `squasher ask` stores the question in the shared thread and returns the thread/message IDs for handoff or later continuation.

Threads are the shared investigation record for terminal, web, Slack, API, and MCP Code Mode workflows. Use `threads list --incident <display-id-or-uuid>` to find the durable conversation for one incident, including messages from its Slack war room. Human messages keep the sender metadata when it is available; assistant and system messages render with the Squasher avatar in the dashboard.

## AI and hosted runs

```bash theme={null}
squasher agent-observations list --project <project_id>
squasher agent-observations quality --project <project_id> --fail-under 100 --min-observations 100 --min-scores 1 --require-privacy-mode --max-content-bearing-percent 0
squasher agent-runs list --project <project_id>
squasher agent-runs get --project <project_id> <run_id>
squasher agent-runs events --project <project_id> <run_id> --after 0
squasher fixes list --project <project_id>
squasher fixes get --project <project_id> <run_id>
```

Use `--thread <thread_id>` with `agent-runs create` or `agent-runs list` to
connect execution to the shared investigation. `agent-runs events` returns an
ordered, redacted lifecycle journal and a cursor that can be used to continue
following a run.

Creating or canceling hosted runs is a write action. Ask before running `agent-runs create`, `agent-runs cancel`, or `fixes create`.

## Dashboards, alerts, monitors, and incidents

```bash theme={null}
squasher dashboards list --project <project_id>
squasher dashboards templates --project <project_id>
squasher dashboards inspect-query --project <project_id> --source logs --aggregation count --time-range 1h
squasher dashboards apply --project <project_id> ./dashboard-definition.json
squasher alerts list --project <project_id>
squasher monitors list --project <project_id>
squasher monitors upsert --project <project_id> --name api --kind http --target https://example.com/health
squasher incidents list --project <project_id>
squasher incidents get --project <project_id> <incident_id>
squasher on-call current --project <project_id>
squasher on-call list --project <project_id>
squasher on-call members --project <project_id> --schedule <schedule_id>
squasher on-call calendar --project <project_id> --schedule <schedule_id> --from <iso_time> --to <iso_time>
squasher on-call create --project <project_id> --name "Primary" --timezone America/Los_Angeles --handoff-day 1 --handoff-time 09:00 --member <user_id>
squasher on-call override --project <project_id> --schedule <schedule_id> --user <user_id> --starts <iso_time> --ends <iso_time>
```

Ask before creates, updates, deletes, acknowledgements, resolves, or dashboard applies unless the user explicitly requested the change.

For migrations from PagerDuty, Opsgenie, or Grafana OnCall, map the source rotation to `squasher on-call create`, verify with `current` and `calendar`, then ask before creating overrides or disabling the old schedule.

## Status, replay, and release artifacts

```bash theme={null}
squasher status-pages list --project <project_id>
squasher status-pages components list --project <project_id> --page <status_page_id>
squasher subscribers list --project <project_id> --page <status_page_id>
squasher replays search --project <project_id> --from <iso_time> --to <iso_time>
squasher replays inspect --project <project_id> <session_id>
squasher sourcemaps upload --project <project_id> --service <service> --release <release> ./dist
squasher sourcemaps list --project <project_id> --service <service>
squasher deployments list --project <project_id> --service <service>
squasher deployments create --project <project_id> --provider buildkite --deployment-id build-123 --service api --version 1.2.3 --environment production --status ready
```

Raw replay events and subscriber data can be sensitive. Keep queries bounded and ask before deletion.

## Integrations and log connectors

```bash theme={null}
squasher integrations providers
squasher integrations connect github
squasher integrations connect linear
squasher integrations connect slack
squasher integrations connect railway
squasher integrations connect vercel
squasher data-sources types
squasher data-sources connections list
squasher data-sources connections create --type vercel --display-name "production web"
squasher data-sources streams list --connection-id <connection_id>
squasher data-sources skill --type otlp
squasher log-connectors catalog
squasher log-connectors onboard --project <project_id> --connector-key otlp_http --display-name "OTLP collector"
squasher log-connectors verify --project <project_id> <connection_id>
```

`data-sources` is the agent-friendly wrapper for ingestion setup. It maps to managed log connectors today and gives agents a stable tree for future integrations. Provider actions such as restart, redeploy, unlink, key rotation, and connector deletion need confirmation.

## Agent prompt

```text theme={null}
Use the Squasher CLI. First run read-only discovery with projects, query-guide, and the narrowest relevant list/get command. Prefer the active project from `squasher projects use`; otherwise include --project or SQUASHER_PROJECT_ID. Use bounded time windows for telemetry. Use `squasher logs query` for one-shot searches, `squasher logs insights` for bounded pattern discovery and current-versus-previous field or attribute comparisons, `squasher logs tail` for live debugging, `squasher data-sources` for ingestion setup, and `squasher on-call current/list/calendar` before changing responder rotations. Ask before write, delete, key rotation, provider restart/redeploy, hosted run dispatch, incident state changes, on-call overrides, schedule disablement, or subscriber cleanup.
```

## Related docs

* [Agent DX](/agents)
* [CLI Integration Setup](/integrations/cli-oauth)
* [MCP](/integrations/mcp)
* [API reference](/api-reference/introduction)