Skip to content
autotel

Terminal Viewer

autotel-terminal is a terminal-native trace viewer built with Ink (React for CLIs). It streams OpenTelemetry spans and shows them as traces with a span tree, search, and waterfall view.

Installation

Section titled “Installation”
Terminal window
npm install autotel-terminal autotel

Standalone CLI

Section titled “Standalone CLI”

Run as a standalone OTLP receiver:

Terminal window
npx autotel-terminal

Then point your app at it:

Terminal window
OTEL_EXPORTER_OTLP_PROTOCOL=http/json \
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4319 \
node app.js

CLI Options:

  • -p, --port <port>: Port (default: 4319)
  • -H, --host <host>: Host (default: 127.0.0.1)
  • -t, --title <title>: Dashboard title
  • --model <spec>: AI assistant model (env: AI_MODEL), see AI assistant
  • --base-url <url>: Endpoint for the model (env: AI_BASE_URL)
  • --ai-api-key <key>: API key, overriding the provider’s own variable (env: AI_API_KEY)

In-Process Usage

Section titled “In-Process Usage”

Wire StreamingSpanProcessor directly to your app:

import { init, trace } from 'autotel';
import {
  createTerminalSpanStream,
  renderTerminal,
  StreamingSpanProcessor,
} from 'autotel-terminal';


const processor = new StreamingSpanProcessor(null);


init({
  service: 'my-app',
  spanProcessors: [processor],
});


const stream = createTerminalSpanStream(processor);
renderTerminal({ title: 'my-app' }, stream);


// Spans appear in the terminal as they complete

AI assistant

Section titled “AI assistant”

Press a in the dashboard to ask questions about your telemetry. You pick the model, and its provider reads its own key from the environment:

--model Provider Key Install
openai/gpt-5 (or gateway:openai/gpt-5) Vercel AI Gateway AI_GATEWAY_API_KEY, or a Vercel OIDC token nothing extra
openai:gpt-5 OpenAI OPENAI_API_KEY @ai-sdk/openai
openai-compatible:qwen3 --base-url http://localhost:1234/v1 Any OpenAI-style server AI_API_KEY if it needs one @ai-sdk/openai-compatible
ollama:granite4 Local Ollama none ai-sdk-ollama
Terminal window
npx autotel-terminal --model ollama:granite4

The provider packages are optional peer dependencies, so install the one you use. A provider whose package is missing names the package to install. Name a model to use a remote provider. With no model set, the assistant starts on its own when a local Ollama answers (model granite4) and stays off otherwise.

In process, pass any AI SDK model to renderTerminal(), or a spec string:

import { anthropic } from '@ai-sdk/anthropic';


renderTerminal({ ai: { model: anthropic('claude-sonnet-5-5') } }, stream);

Dashboard Controls

Section titled “Dashboard Controls”
Key Action
/ Search by span name
e Toggle error-only filter
↑/↓ Navigate traces/spans
Enter Expand selected trace
l Toggle logs view
a Toggle the AI assistant
? Help overlay
q Quit

Features

Section titled “Features”
  • Real-time span streaming
  • Parent/child span tree per trace
  • Search and error filtering
  • Span detail view with attributes
  • Waterfall visualization
  • Relative time labels

Examples

Section titled “Examples”
  • example-terminal: Interactive terminal dashboard with live span streaming, error filtering, and P95 latency.

OTLP Endpoints (Standalone)

Section titled “OTLP Endpoints (Standalone)”
Endpoint Signal
POST /v1/traces Traces
POST /v1/logs Logs
POST /v1/metrics Metrics
GET /healthz Health check