CLI

autotel-cli provides an interactive setup wizard, a static observability score for your codebase, diagnostics, incremental feature additions, and telemetry investigation commands.

Installation

npm install -g autotel-cli
# or
npx autotel <command>

Commands

autotel init

Interactive setup wizard:

# Interactive mode
npx autotel init

# Use defaults
npx autotel init --yes

# Use a quick preset
npx autotel init --preset node-datadog-pino

# Dry run
npx autotel init --dry-run

Quick presets:

• node-datadog-pino: Node.js + Datadog + Pino logging
• node-datadog-agent: Node.js + Datadog Agent (local dev)
• node-honeycomb: Node.js + Honeycomb
• node-otlp: Node.js + Generic OTLP endpoint

autotel map

Score the observability of every entry point in your codebase. Static analysis, so nothing runs and nothing leaves the machine:

npx autotel map                              # score + the three to fix first
npx autotel map --all                        # every entry point as a matrix
npx autotel map src/routes/checkout.ts       # one entry point and its fixes
npx autotel map --json --no-write            # for agents
npx autotel map --min-score 70               # CI floor
npx autotel map --baseline git:origin/main   # CI ratchet

See Observability Map for the checks, the scoring, and the autotel.map.json contract.

autotel doctor

Run diagnostics on your setup:

npx autotel doctor          # Run all checks
npx autotel doctor --json   # Machine-readable output
npx autotel doctor --fix    # Auto-fix resolvable issues

autotel add <type> <name>

Add components incrementally:

npx autotel add backend datadog
npx autotel add subscriber posthog
npx autotel add plugin bigquery
npx autotel add platform cloudflare

autotel investigate surface

The CLI can query and diagnose telemetry directly (same backend model as autotel-mcp), returning one JSON document per invocation.

# backend health + signal availability
npx autotel health
npx autotel capabilities

# discovery
npx autotel discover services
npx autotel discover trace-fields
npx autotel discover log-fields

# traces / spans / logs / metrics
npx autotel query traces --service-name checkout --error-only --limit 20
npx autotel query spans --service-name checkout --operation-name db.query
npx autotel query logs --trace-id <traceId>
npx autotel query metrics --service-name checkout

# incident triage
npx autotel diagnose anomalies --service checkout
npx autotel diagnose root-cause <traceId>
npx autotel correlate trace <traceId>

# security triage (security.* schema)
npx autotel security summary --lookback-minutes 60
npx autotel security events --severity critical --lookback-minutes 240

# MCP protocol-boundary security (mcp.security.* / mcp.tool.*)
npx autotel security mcp --lookback-minutes 60

The security summary / security events commands read the stable security.* schema emitted by autotel-audit. See Security Observability for the full picture. security mcp aggregates the MCP signals emitted by autotel-mcp-instrumentation (prompt-injection verdicts, output-budget breaches, untrusted-content tool calls). See MCP.

All backend-touching commands accept:

--backend collector|jaeger|tempo|prometheus|loki|stack|auto|fixture|logfire|datadog|signoz
--jaeger-base-url <url>
--tempo-base-url <url>
--prometheus-base-url <url>
--loki-base-url <url>
--collector-port <n>
--fixture-path <path>
--logfire-base-url <url>
--datadog-site <site>
--signoz-base-url <url>

Hosted vendors

logfire, datadog and signoz are trace-only — capabilities reports their metrics and logs as unsupported rather than returning empty results, so you can tell “this backend can’t answer that” from “there’s nothing there”.

Their credentials are read from the environment and never accepted as flags, because argv is readable from the process table:

Backend	Credentials
logfire	LOGFIRE_READ_TOKEN — must be read-scope; the query API rejects write tokens
datadog	DD_API_KEY and DD_APP_KEY — an application key is separate from the API key
signoz	SIGNOZ_API_KEY — omit for an unauthenticated self-hosted instance

DD_SITE accepts a bare site (uk1.datadoghq.com) or a full API URL. For Logfire, note that ingest and queries use different hosts: writes go to the regional OTLP host selected by createLogfireConfig, while LOGFIRE_BASE_URL for reads must name the same region (logfire-us / logfire-eu). SigNoz reads use its Query Builder v5 API.

Hosted read APIs retry HTTP 429 responses with bounded backoff and honour Retry-After. If the retry budget is exhausted, command JSON reports AUTOTEL_E_RATE_LIMITED with retryable: true; agents should wait for the vendor’s rate-limit window and retry instead of interpreting it as “no data”.

Ingest lag

npx autotel health --otlp-endpoint http://localhost:4318

Writes one probe span and polls until it reads back, reporting freshness.timeToQueryableSeconds. Backends differ by two orders of magnitude here, and on a slow one a write-then-read loop sees nothing and wrongly concludes no telemetry was emitted — so check this before trusting an empty result.

The probe sends OTLP protobuf by default (the encoding every OTLP/HTTP receiver must accept); the built-in collector reads JSON and is switched automatically. Override with --otlp-encoding json|protobuf, bound the wait with --freshness-timeout-ms, and authenticate hosted endpoints through the standard OTEL_EXPORTER_OTLP_HEADERS — which for most vendors is the write credential, not the read token used for querying.

The timeout bounds both the write and every backend read. Authentication and configuration failures are returned immediately rather than being disguised as ingest lag. Vendor endpoint path prefixes are preserved when /v1/traces is appended.

Use --output-file <path> to persist command JSON and --no-secrets-in-output to redact secret-shaped values.

autotel codemod trace <path>

Wrap functions with trace():

npx autotel codemod trace ./src

Examples

See any example app. autotel init generates the instrumentation.ts file used across all examples.

Related

• Observability Map: the autotel map scoring surface in full.
• MCP: the autotel-mcp server this CLI investigate surface mirrors.
• Claude Code Skill: using these commands from a Claude skill workflow.
• Devtools: local OTLP receiver UI. Run it with npx autotel-devtools (not npx autotel dev tools).