Vercel CLI adds trace span search so developers and agents can debug from the terminal

Vercel has added trace span search to its command line tool. According to the company's changelog, the new vercel traces search command brings observability data into the terminal, letting developers — and coding agents — investigate errors, latency and security-sensitive behavior without opening the Vercel dashboard.

Searching spans from the terminal

A span represents a single step in a request, which makes it the natural unit for working out where something went wrong or slowed down. Previously, that kind of investigation meant opening the dashboard; the new command keeps the workflow in the shell.

By default, vercel traces search returns up to 100 spans from the last hour, sorted newest first. That default removes a common prerequisite: you don't need to know a request ID or trace ID before you can start. Run the command, see what's recent, then narrow things down.

The command ships dedicated filters for environment, service, span name, status, deployment ID, request ID, trace ID and span ID, plus --since and --until for time ranges. Two examples from the changelog:

text

error spans from the last hour

vercel traces search --status error --since 1h

every span in one trace

vercel traces search --trace-id 4bf92f3577b34da6a3ce929d0e0e4736

KQL queries and JSON output

For anything without a dedicated flag, --query accepts a subset of Kibana Query Language (KQL). The changelog notes that it covers fields such as duration, along with span and resource attributes, so a query like the one below finds spans slower than two seconds:

text vercel traces search --query 'span.duration > 2000'

A -- flag outputs one JSON object per span. The changelog describes this as structured data for scripts and agents to analyze — machine-readable output rather than formatted terminal text that automated tooling would otherwise have to scrape.

Availability

The feature arrives with a CLI update: run vercel upgrade to get the latest version, then vercel traces search --help for the full option list. Vercel points to its vercel traces documentation for further details.

Why it matters

Observability data has historically lived in web dashboards, which works well for humans in a browser but poorly for two increasingly common workflows: terminal-first development and automated coding agents.

This change serves both. For developers, the back-and-forth of finding an identifier in one place and pasting it into a dashboard disappears — a quick --status error --since 1h search gives an immediate view of what just broke, and drilling into a full trace is one flag away. For agents, the JSON output means diagnosis can happen inside the same toolchain that writes and deploys the code: an agent that notices a failing deployment can pull the relevant spans, locate the erroring or slow step, and act on it without a human relaying information between browser and terminal.

The framing is also worth noting. The changelog names coding agents as a primary audience alongside developers, another sign that vendors are designing developer tools on the assumption that the user may be a program. Structured output and an expressive query syntax are exactly the kind of interface that serves a person typing in a shell and an agent driving one equally well.