CLI Reference
tael is the single binary for both the server and the client. Client commands talk to the REST API over HTTP; tael serve runs the server itself. Every command takes the global flags below.
Global flags
These work on any command:
- Name
--format- Type
- json | table (default json)
- Description
Output format. JSON is the default so agents can parse it;
tableis for humans.
- Name
--server- Type
- URL (default http://127.0.0.1:7701)
- Description
REST API address for client commands.
- Name
--port-rest- Type
- u16
- Description
Shorthand: for clients, equivalent to
--server http://127.0.0.1:<port>; forserve, sets the REST listen port. Conflicts with--server.
- Name
--port-otel- Type
- u16
- Description
serveonly — sets the OTLP gRPC listen port on127.0.0.1.
Duration format (used by --last, --baseline, --min-duration, etc.): 500 (bare = ms), 100ms, 1s, 5m, 1h, 24h, 7d.
serve
Run the server: OTLP gRPC ingest, storage, and the REST API in one process.
- Name
--otlp-grpc-addr- Type
- addr
- Description
- OTLP gRPC listen address. Env:
TAEL_OTLP_GRPC_ADDR. Default127.0.0.1:4317.
- Name
--rest-api-addr- Type
- addr
- Description
- REST API listen address. Env:
TAEL_REST_API_ADDR. Default127.0.0.1:7701.
- Name
--data-dir- Type
- path
- Description
- Data directory. Env:
TAEL_DATA_DIR. Default~/.tael/data.
- Name
--wal-dir- Type
- path
- Description
- WAL directory. Env:
TAEL_WAL_DIR. Default~/.tael/wal_files.
- Name
--storage- Type
- tael-backend | duckdb
- Description
- Storage backend. Env:
TAEL_STORAGE. Defaulttael-backend.
tael serve
tael serve --rest-api-addr 0.0.0.0:7701 --data-dir /var/lib/tael/dataquery traces
Search and filter spans.
- Name
--service- Type
- string
- Description
- Exact service match.
- Name
--operation- Type
- string
- Description
- Substring match on the span operation.
- Name
--min-duration / --max-duration- Type
- duration
- Description
- Duration bounds (e.g.
500ms,1s).
- Name
--status- Type
- ok | error | unset
- Description
- Filter by span status.
- Name
--attribute- Type
- key=value (repeatable)
- Description
- Exact attribute match; repeated flags are ANDed.
- Name
--text- Type
- string
- Description
- Full-text search over LLM payload blobs (
tael-backendonly).
- Name
--last- Type
- duration
- Description
- Time window.
- Name
--limit- Type
- int (default 100)
- Description
- Max results.
tael query traces --service api --status error --last 1h --format table
tael query traces --min-duration 500ms --attribute http.method=GET --attribute http.status_code=500
tael query traces --text "rate limit" --last 24hquery logs
Search and filter log records.
- Name
--service- Type
- string
- Description
- Exact service match.
- Name
--severity- Type
- trace | debug | info | warn | error | fatal
- Description
- Name
--body-contains- Type
- string
- Description
- Substring search over the log body.
- Name
--trace-id- Type
- string
- Description
- Logs emitted within this trace.
- Name
--last- Type
- duration
- Description
- Name
--limit- Type
- int (default 100)
- Description
tael query logs --severity error --last 1h
tael query logs --service payments --body-contains "timeout"
tael query logs --trace-id abc123def456query metrics
Two modes: a simple filter, or a PromQL subset via --query.
- Name
--query- Type
- PromQL
- Description
- PromQL subset expression. When set,
--service/--name/--typeare ignored.
- Name
--service- Type
- string
- Description
- Name
--name- Type
- string
- Description
- Exact metric name.
- Name
--type- Type
- gauge | sum | histogram | summary
- Description
- Name
--last- Type
- duration
- Description
- Name
--limit- Type
- int (default 500)
- Description
tael query metrics --name http_requests --service api --last 5m
tael query metrics --query 'rate(http_requests{service="api"}[5m])'
tael query metrics --query 'sum by (service) (http_requests)'Supported PromQL subset: bare and labelled selectors (metric{label="v", other!="x"}), rate(expr[5m]) (naive counter-reset clamp), and sum|avg|min|max|count(expr) with optional by (...). Synthetic labels: service, __name__. Not supported: binary ops, without(...), regex matchers (=~, !~), offset, subqueries, histogram_quantile, topk, quantile, stddev, range queries.
query sql
Run a read-only SQL query (SELECT / WITH only) over the telemetry tables: spans, logs, metrics, trace_comments.
tael query sql "SELECT service, COUNT(*) AS n FROM spans WHERE status='error' GROUP BY service ORDER BY n DESC"
tael query sql "SELECT * FROM spans WHERE trace_id='abc123' ORDER BY start_time"get
Get a specific resource by ID.
# Every span in a trace, ordered by start time
tael get trace abc123def456 --format tableservices
List known services with span_count, trace_count, avg_duration_ms, and error_rate.
tael services --format table
tael services --format json | jq '.services | sort_by(.error_rate) | reverse'summarize
Aggregated health summary over a window: trace count, top services, top error operations, log/metric volume.
- Name
--last- Type
- duration (default 1h)
- Description
- Name
--service- Type
- string
- Description
- Filter to a single service.
tael summarize --last 15m --format tableanomalies
Surface services whose error rate or p95 latency regressed versus a baseline window.
- Name
--last- Type
- duration (default 1h)
- Description
- Current window.
- Name
--baseline- Type
- duration (default 6× current)
- Description
- Baseline window to compare against.
- Name
--service- Type
- string
- Description
tael anomalies --last 5m --baseline 30mcorrelate
Pull spans, logs, and metrics for one trace ID in a single cross-signal query.
- Name
--trace- Type
- trace_id (required)
- Description
tael correlate --trace abc123def456watch
Poll the summary endpoint on an interval and print signed deltas between samples — programmatic monitoring for an agent.
- Name
--last- Type
- duration (default 1m)
- Description
- Summary window per sample.
- Name
--service- Type
- string
- Description
- Name
--interval- Type
- seconds (default 10)
- Description
tael watch --last 1m --interval 10 --service cartcomment
Add or view trace comments.
# add <trace_id> "<body>" [--author <name>] [--span-id <id>]
tael comment add abc123def456 "Root cause: expired DB pool" --author oncall-bot
tael comment add abc123def456 "Needs an index" --span-id xyz789 --author claude
# list <trace_id>
tael comment list abc123def456--author defaults to cli.
live
Interactive TUI: live trace feed, service health, waterfall visualizer, eval progress. See The Live TUI for flags and keyboard controls.
tael live --service api-gateway
tael live --evalseval
Collect, score, report, and compare trace-native evals.
tael eval run cases.jsonl --suite regression --cmd 'python run_case.py {case_id}'
tael eval score <run_id> scores.jsonl
tael eval runs
tael eval status <run_id>
tael eval cases <run_id>
tael eval report <run_id> --format table
tael eval compare <run_id> <baseline_run_id>
tael eval case add --from-trace <trace_id> --suite golden --case-id <id> --failure-mode tool_error
tael eval case link --case-id <id> --issue-id <id>
tael eval suite inspect <suite>issue
Classify production failures into recurring issues.
tael issue create --from-trace <trace_id> --failure-mode tool_error --impact high --summary "..."
tael issue list
tael issue examples <issue_id>--impact is one of low | medium | high | critical.
signal / experiment / diagnose
tael signal— define and inspect long-running reliability signals.tael experiment compare <exp_id>— compare production experiment variants (--signal,--metric,--last).tael diagnose— record and list untrusted agent self-diagnostics.
server
Server management.
tael server status # health-check the serverskill
Install the Tael Claude Code skill so an agent knows how to drive these commands.
tael skill install --project # into ./.claude/skills/tael/
tael skill install # into ~/.claude/skills/tael/
tael skill where # print the destination path only--force overwrites an existing install.