Insight CLI

Use the Insight CLI to operate an Insight project from the terminal. It talks only to the public REST API, so requests use the same authentication, project scoping, and rate limits as browser and SDK traffic.

The CLI is useful for read-only diagnostics, SQL analytics, dashboard and widget management, trace viewer config management, and repeatable smoke checks in CI.

Install

The CLI command is insight. Install it from npm:

npm install -g @mantisai/insight-cli

insight --help

Authenticate

Use project API keys from Insight. The CLI accepts credentials from either environment variables or a saved profile.

Environment variables

export INSIGHT_HOST="https://insight.withmetis.ai"
export INSIGHT_PUBLIC_KEY="pk-lf-..."
export INSIGHT_SECRET_KEY="sk-lf-..."
 
insight auth whoami

Saved profile

insight auth login \
  --host "https://insight.withmetis.ai" \
  --public-key "pk-lf-..." \
  --secret-key "sk-lf-..."
 
insight auth whoami

Saved profiles live in ~/.insight/config.json. Environment variables override saved profiles, which is usually the cleanest path for CI and smoke tests.

⚠️

Do not commit real keys into scripts or project configuration. Use placeholders in docs and inject real values through your shell, CI secret store, or local profile.

Read-only smoke test

Run these commands when you want to confirm the CLI can authenticate, reach the hosted Insight API, and query trace data without creating or deleting anything.

insight health --json
insight ready --json
insight traces list --limit 3 --fields core
insight projects list
insight dashboards list --limit 5
insight sessions list --limit 3
insight observations list --limit 3
insight scores list --limit 3
insight trace-viewer-configs list

Check ClickHouse-backed SQL access with a small date range query:

insight sql \
  "SELECT count() AS total, min(timestamp) AS earliest, max(timestamp) AS latest FROM traces" \
  --json

If the project has stale data, a "last 14 days" query can return zero even when the CLI is working correctly:

insight sql \
  "SELECT count() AS recent_14d FROM traces WHERE timestamp >= now() - INTERVAL 14 DAY" \
  --json

Common commands

Trace exploration

insight traces list --limit 20
insight traces list --name "conversation_turn" --limit 10
insight traces get "<trace-id>" --json

Use --from and --to for old projects so the query window matches the data:

insight traces list \
  --from "2026-01-01T00:00:00Z" \
  --to "2026-02-01T00:00:00Z" \
  --limit 20

SQL analytics

insight sql "SELECT name, count() AS cnt FROM traces GROUP BY name ORDER BY cnt DESC LIMIT 10"
insight sql "SELECT type, count() AS cnt FROM observations GROUP BY type ORDER BY cnt DESC" --json
insight sql "SELECT name, avg(value) AS avg_value FROM scores GROUP BY name ORDER BY name" --csv

The CLI SQL command uses raw table names: traces, observations, and scores.

Dashboards and viewer configs

insight dashboards list
insight widgets list
insight trace-viewer-configs list

Create, update, and delete commands are also available, but keep smoke tests read-only unless you intentionally want to mutate the project.

Skills

insight skills list
insight skills run health-check
insight skills run analytics

Built-in skills use the same REST and SQL APIs as the rest of the CLI. They are useful for guided diagnostics, but they may read more data than the minimal smoke commands above.

OTLP endpoint note

INSIGHT_OTLP_ENDPOINT is used by SDK and OpenTelemetry export flows. The insight CLI does not read that variable. For trace export, see OTel Ingestion and Insight Export.

Troubleshooting

`fetch failed`

The CLI could not reach the host. Check network access, DNS, proxy settings, and that INSIGHT_HOST has the correct scheme:

export INSIGHT_HOST="https://insight.withmetis.ai"

`401` or `403`

The project keys are missing, copied incorrectly, revoked, or scoped to a different project. Regenerate keys in Insight and retry with fresh environment variables.

Empty trace results

Empty results do not always mean auth is broken. Check the project date range:

insight sql \
  "SELECT count() AS total, min(timestamp) AS earliest, max(timestamp) AS latest FROM traces" \
  --json

Then rerun trace and SQL commands with date filters that overlap the returned range.

Next steps

Insight SQL API Tracing Module