Why This Matters

You’ve optimized your site, but how do you know it’s actually faster for real users? Browser DevTools only simulate one device. RUM (Real User Monitoring) data from Vercel Speed Insights gives you the truth—but navigating a dashboard can interrupt your flow.

Now, you don’t have to. The Vercel CLI exposes Speed Insights data directly via the vercel metrics command. This means your coding agent or CI pipeline can ask questions like:

  • Which pages’ INP has regressed since last week?
  • How is the perceived speed of my home page in Asia?
  • Compare the CLS of the dashboard between mobile and desktop.

No more context switching. Let’s make it work.

Developer using Vercel CLI to query Speed Insights for Core Web Vitals on a terminal Software Concept Art

Getting Started with vercel metrics

First, ensure you have the latest Vercel CLI installed:

npm i -g vercel@latest

Then authenticate if you haven’t already:

vercel login

Now you can query metrics. The basic syntax:

vercel metrics --metric LCP --dimension page --filter country=US

Example: Find pages with regressed INP

# Compare this week vs last week for Interaction to Next Paint
vercel metrics \
  --metric INP \
  --dimension page \
  --filter period=7d \
  --compare period=7d_offset=7

This returns a table of pages where INP increased (regressed). You can pipe this into jq or a CI script to alert your team.

Example: Perceived speed in Asia

vercel metrics \
  --metric LCP \
  --dimension country \
  --filter country=JP,KR,CN,SG,IN

Example: Mobile vs Desktop CLS

vercel metrics \
  --metric CLS \
  --dimension device \
  --filter device=mobile,desktop

For a full list of supported metrics (LCP, INP, CLS, FCP, TTFB) and dimensions (page, country, device, etc.), check the official Vercel documentation.

Pro tip: Use this in a GitHub Action to fail a PR if any key metric regresses beyond a threshold.

Vercel CLI output showing LCP, INP, CLS metrics from real user traffic IT Technology Image

Limitations & Caveats

  • Data availability: Metrics are only available for projects with Speed Insights enabled and sufficient traffic. Low-traffic pages may show no data.
  • Sampling: Real user data is sampled; very small sample sizes can be noisy.
  • CLI version: Requires Vercel CLI 34.0+. Run vercel --version to check.
  • Filtering granularity: Some filters (e.g., custom dimensions) are not yet exposed via CLI—stick to built-in dimensions for now.

Next Steps

  • Automate performance regression checks in your CI/CD pipeline.
  • Combine with synthetic testing (e.g., Lighthouse CI) for a complete picture.
  • Explore the Vercel Insights API for programmatic access beyond CLI.

Dashboard comparing mobile and desktop CLS scores queried via Vercel CLI Developer Related Image

Conclusion

The vercel metrics command turns your terminal into a performance observability tool. No more switching to a dashboard for every question. Whether you’re debugging a regression, comparing regions, or setting up CI gates, this CLI command keeps you in the flow.

If you’re also concerned about securing your AI-powered agents, check out our guide on defending against frontier AI models with Cloudflare’s architecture. And for building trustable AI beyond chatbots, read about Google’s Antigravity Framework.

Go ahead—run vercel metrics and see what your real users are experiencing.

This content was drafted using AI tools based on reliable sources, and has been reviewed by our editorial team before publication. It is not intended to replace professional advice.