[cli] Add logsv2 command (#14656)

## Summary

Adds a new hidden `vercel logsv2` command that uses the newer
`/api/logs/request-logs` endpoint (same as the Vercel dashboard). This
provides project-scoped log querying with extensive filtering options,
designed to eventually replace the existing `logs` command.

## New Features

- **Project-scoped logs**: Query logs across all deployments in a
project (vs deployment-only in v1)
- **Rich filtering**: Level, source, status code, environment, time
range, request ID, and full-text search
- **Agent-native output**: JSON Lines format for easy piping to `jq` and
automation tools
- **Historical data**: Query past logs with `--since`/`--until` (vs
real-time only in v1)

## New Options

| Option | Type | Description |
|--------|------|-------------|
| `--project, -p` | string | Project ID or name (defaults to linked
project) |
| `--deployment, -d` | string | Filter to specific deployment ID or URL
|
| `--environment` | string | `production` or `preview` |
| `--level` | string[] | `error`, `warning`, `info`, `fatal`
(repeatable) |
| `--status-code` | string | HTTP status code filter (e.g., `500`,
`4xx`) |
| `--source` | string[] | `serverless`, `edge-function`,
`edge-middleware`, `static` |
| `--since` | string | Start time (ISO date or relative: `1h`, `30m`,
`2d`) |
| `--until` | string | End time (default: now) |
| `--limit, -n` | number | Maximum results (default: 100) |
| `--json, -j` | boolean | Output as JSON Lines for piping |
| `--query, -q` | string | Full-text search query |
| `--request-id` | string | Filter by request ID |

## Agent-Native Design

The command follows CLI best practices for automation:

- **JSON Lines output** (`--json`): Each log entry is a separate JSON
object on its own line
- **stdout/stderr separation**: Log data to stdout, status messages to
stderr
- **Clear exit codes**: 0 = success, 1 = error, 2 = help displayed
- **TTY detection**: Pretty output for terminals, plain for pipes
- **NO_COLOR support**: Respects color preferences

## Usage Examples

```bash
# View recent errors for linked project
vercel logsv2 --level error --since 1h

# Search logs with JSON output for jq processing
vercel logsv2 --json --query "timeout" | jq '.statusCode'

# Filter by deployment and status code
vercel logsv2 --deployment dpl_abc123 --status-code 500

# Production errors in the last day
vercel logsv2 --environment production --level error --since 1d

# Filter by specific request ID
vercel logsv2 --request-id req_xxxxx
```

## Comparison: logs vs logsv2

| Feature | `logs` (v1) | `logsv2` (new) |
|---------|-------------|----------------|
| Scope | Single deployment | Project-wide (+ optional deployment
filter) |
| Data access | Real-time streaming | Historical via pagination |
| Filtering | None (use jq) | level, source, status, environment,
request ID, search |
| Time range | "now" only | `--since` / `--until` |
| API | `/v1/.../runtime-logs` (streaming) | `/api/logs/request-logs`
(REST) |
| Timeout | 5 minutes auto-abort | None |

## Breaking Changes

None - this is a new hidden command. The existing `logs` command is
unchanged.

## Rollout Strategy

1. **Phase 1 (this PR)**: Hidden `vercel logsv2` command for testing
2. **Phase 2**: Feature flag to redirect `vercel logs` → `logsv2`
3. **Phase 3**: Promote to default, deprecate v1

## Test Plan

- [x] Unit tests for `logs-v2.ts` utility (18 tests)
- [x] Unit tests for `logsv2` command (34 tests)
- [x] Manual testing with linked project
- [x] Manual testing with `--project` flag
- [x] Verify JSON output pipes correctly to `jq`
- [ ] Test all filter combinations

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: adriancooney

.changeset/logsv2-command.md

@@ -0,0 +1,5 @@
+---
+"vercel": patch
+---
+
+Add hidden `logsv2` command with request-logs API support

packages/cli/src/commands/index.ts

@@ -22,6 +22,7 @@ import { listCommand } from './list/command';
 import { loginCommand } from './login/command';
 import { logoutCommand } from './logout/command';
 import { logsCommand } from './logs/command';
+import { logsv2Command } from './logsv2/command';
 import { mcpCommand } from './mcp/command';
 import { microfrontendsCommand } from './microfrontends/command';
 import { openCommand } from './open/command';
@@ -67,6 +68,7 @@ const commandsStructs = [
   loginCommand,
   logoutCommand,
   logsCommand,
+  logsv2Command,
   mcpCommand,
   microfrontendsCommand,
   openCommand,

packages/cli/src/commands/logsv2/command.ts

@@ -0,0 +1,126 @@
+import { packageName } from '../../util/pkg-name';
+
+export const logsv2Command = {
+  name: 'logsv2',
+  aliases: [],
+  description: 'Display request logs for a project using the new logs API.',
+  hidden: true,
+  arguments: [],
+  options: [
+    {
+      name: 'project',
+      shorthand: 'p',
+      type: String,
+      deprecated: false,
+      description: 'Project ID or name (defaults to linked project)',
+    },
+    {
+      name: 'deployment',
+      shorthand: 'd',
+      type: String,
+      deprecated: false,
+      description: 'Filter logs to a specific deployment ID or URL',
+    },
+    {
+      name: 'environment',
+      shorthand: null,
+      type: String,
+      deprecated: false,
+      description: 'Filter by environment: production or preview',
+    },
+    {
+      name: 'level',
+      shorthand: null,
+      type: [String],
+      deprecated: false,
+      description: 'Filter by log level: error, warning, info, fatal',
+    },
+    {
+      name: 'status-code',
+      shorthand: null,
+      type: String,
+      deprecated: false,
+      description: 'Filter by HTTP status code (e.g., 500, 4xx)',
+    },
+    {
+      name: 'source',
+      shorthand: null,
+      type: [String],
+      deprecated: false,
+      description:
+        'Filter by source: serverless, edge-function, edge-middleware, static',
+    },
+    {
+      name: 'since',
+      shorthand: null,
+      type: String,
+      deprecated: false,
+      description: 'Start time (ISO format or relative: 1h, 30m)',
+    },
+    {
+      name: 'until',
+      shorthand: null,
+      type: String,
+      deprecated: false,
+      description: 'End time (ISO format or relative, default: now)',
+    },
+    {
+      name: 'limit',
+      shorthand: 'n',
+      type: Number,
+      deprecated: false,
+      description: 'Maximum number of results (default: 100)',
+    },
+    {
+      name: 'json',
+      shorthand: 'j',
+      type: Boolean,
+      deprecated: false,
+      description: 'Output logs as JSON Lines for piping to other tools',
+    },
+    {
+      name: 'query',
+      shorthand: 'q',
+      type: String,
+      deprecated: false,
+      description: 'Full-text search query',
+    },
+    {
+      name: 'request-id',
+      shorthand: null,
+      type: String,
+      deprecated: false,
+      description: 'Filter by request ID',
+    },
+  ],
+  examples: [
+    {
+      name: 'Display recent logs for the linked project',
+      value: `${packageName} logsv2`,
+    },
+    {
+      name: 'Display error logs from the last hour',
+      value: `${packageName} logsv2 --level error --since 1h`,
+    },
+    {
+      name: 'Display logs for a specific deployment',
+      value: `${packageName} logsv2 --deployment dpl_xxxxx`,
+    },
+    {
+      name: 'Filter logs by status code and output as JSON',
+      value: `${packageName} logsv2 --status-code 500 --json`,
+    },
+    {
+      name: 'Search logs and pipe to jq',
+      value: `${packageName} logsv2 --query "timeout" --json | jq '.message'`,
+    },
+    {
+      name: 'Display production logs only',
+      value: `${packageName} logsv2 --environment production`,
+    },
+    {
+      name: 'Display logs for a specific request',
+      value: `${packageName} logsv2 --request-id req_xxxxx`,
+    },
+  ],
+} as const;