Vercel's comments CLI (20 Aug 2026) drops the delete prompt in JSON mode, and its doc is dated 2018

Summary. Vercel published vercel comments on 20 August 2026, described in the changelog as covering "the full triage loop" for Vercel Toolbar comments and offering "--format json output for scripts and agents." Three things in the reference page deserve attention before you point an agent at it. First, the JSON contract: "JSON output does not prompt for missing input or confirmation," while the delete section says "Deletion cannot be undone." Second, the page's own frontmatter reports last_updated: 2018-10-20 — eight years before the feature shipped — against 2026-06-16 on /docs/comments and 2026-02-26 on /docs/comments/managing-comments. Third, the machine-readable Markdown rendering at /docs/cli/comments.md, which Vercel is text/markdown and annotates with a "For AI agents" block, cuts its "Permissions Required" callout off mid-sentence after the words "The vercel comments command". The command ships in the npm vercel package, 59.5.0 as of 22 August 2026, Apache-2.0, Node 18 or later. List results default to 20 threads with a maximum of 100, and replies accept up to 10 attachments by HTTPS URL only.

What shipped, and what the changelog claims

The 20 August 2026 changelog post, credited to Julian Benegas, Vishal Yathish and George Karagkiaouris, lists four capabilities: listing and filtering unresolved comments for the linked project scoped to the current Git branch, inspecting a full thread with every message and its IDs, replying, resolving, reopening, editing or deleting from the terminal, and --format json output for scripts and agents.

That is an accurate description of the surface. vercel comments with no subcommand runs list; inspect prints every message and its message ID; reply takes --message, --file or standard input; resolve, reopen, edit and delete all take thread IDs or full vercel.com comment URLs.

The interesting part is what happens when you add --json.

The JSON contract inverts the safety model

The reference page's JSON section states, without qualification: "Use --json or --format json with any subcommand except open. JSON output does not prompt for missing input or confirmation."

Read that against the delete section three headings earlier: "Deletion cannot be undone. The command asks for confirmation by default. Pass --yes in non-interactive or JSON mode."

The two paragraphs do not agree. If JSON output never prompts for confirmation, --yes is redundant in JSON mode; if --yes is needed in JSON mode, JSON output does prompt. Only one of those can be true at runtime, and the page does not say which. The safe assumption for anyone writing an agent is the more dangerous one: that vercel comments delete <thread> <message-id> --json removes a message with no gate and no undo.

Compare that with the sibling release one day later. Vercel's 21 August 2026 CLI post added vercel project and vercel domains subcommands, and there the reference is explicit that --format json "only changes the output format and the confirmation will come first." We looked at that half of the split in detail in our note on Vercel CLI project and domain commands that block CI.

Behaviour	vercel comments (20 Aug 2026)	vercel project (21 Aug 2026)
JSON flag	--json or --format json	--format json
Effect of JSON on prompts	"does not prompt for missing input or confirmation"	"the confirmation will come first"
Skip-confirmation flag	-y, --yes documented	none on eight subcommands
Riskiest documented action	delete, "cannot be undone"	pause, reversible with resume
Usable unattended	yes	no

The CLI that gates a reversible pause behind a typed project name is the same CLI that will, on the reading its own docs support, delete an irreversible message because a flag changed the output format.

A reference page dated 20 October 2018

Every Vercel docs page carries last_updated in its frontmatter. /docs/cli/comments reports 2018-10-20. The feature it documents was announced on 20 August 2026.

This is not a nitpick about a date field. It is the signal a reader or a retrieval system uses to decide whether a page reflects current behaviour, and here it points eight years in the wrong direction. The neighbouring pages are dated normally: /docs/comments at 16 June 2026, /docs/vercel-toolbar at 26 June 2026, /docs/comments/managing-comments at 26 February 2026, /docs/cli/api at 15 July 2026. The 2018 stamp on the newest page in the set looks like a template default that was never filled in, and we have seen the same fingerprint on another Vercel CLI page this month.

The truncated callout compounds it. The page opens with a "Permissions Required" note, and in the Markdown rendering the note ends after five words: "The vercel comments command". Nothing follows. Vercel serves that Markdown at /docs/cli/comments.md with a text/markdown content type and embeds a "For AI agents" block in it, so an agent asked "what permissions does vercel comments delete need?" reads a sentence with no answer in it. There is no permission matrix anywhere else on the page.

The scoping rules that will surprise a CI job

Three documented behaviours change what a scripted run actually returns.

Branch inference is conditional. The reference says list "uses the linked project and filters by the current Git branch when it can infer one," and that "branch inference applies only when that project matches the current checkout." Pass --project to point at a different project and the branch filter silently stops applying, so the same command returns a different set of threads depending on where it runs. Use --branch or --all-branches explicitly in any automation.

--author me needs a user, not a token. The option filters "by a user ID or me," and the page adds that "me requires user authentication, and usernames are not supported." A CI job authenticating with VERCEL_TOKEN, which is the method Vercel's own CLI page recommends for pipelines, is not user authentication. Resolve the user ID once and hardcode it, or the filter fails in the environment you most wanted it in.

Page paths are recorded, not derived. --page <PATH> filters "by a recorded page path or glob," and the page warns that "rewrites can cause the recorded path to differ from the browser URL." If your Next.js app rewrites /checkout to /en/checkout, a filter written against the URL a reviewer pasted into Slack will match nothing.

Bulk operations hide partial failure in the exit code

resolve and reopen accept multiple thread IDs. The reference states: "Bulk operations continue after an individual thread fails and exit with a nonzero status if any operation fails."

That is a reasonable design and a bad fit for a naive script. A run that resolved 19 of 20 threads and a run that resolved none both exit non-zero, and the shell sees the same number. The JSON output is where the difference lives: resolve and reopen with multiple threads return "an object with a results array containing the result for each thread," while the single-thread form returns an object with thread and replied. So the response shape changes with the number of arguments. Any wrapper needs to branch on that, and any retry logic needs to read results rather than trusting the exit code, or it will re-resolve the 19 threads that already succeeded.

Pagination has the same shape problem in a milder form. --limit accepts 1 to 100 and defaults to 20. Text output prints the --next command with the next cursor; JSON output returns it as pagination.nextCursor. A script that parses the text form breaks the moment someone adds --json.

Who is affected

Teams wiring Toolbar comments into an agent loop are the intended audience of this release and carry all of the risk in it. If an agent has permission to run vercel comments delete --json, treat that as a destructive capability with no undo and no documented permission boundary, and remove delete from the allowed command list until Vercel clarifies the prompt behaviour.

Teams building a review-triage bot should stay on the read and reply surface. list, inspect and reply are safe: nothing there is irreversible, reply takes standard input so git log -1 --format=%s | vercel comments reply <thread> works, and attachments are limited to 10 HTTPS URLs with no local upload path, which keeps the blast radius small.

Teams running comments across many projects need explicit scope flags everywhere, because the branch inference rule above makes the default non-deterministic across environments.

What to do now

Pin the CLI. The npm vercel package was at 59.5.0 published 22 August 2026 under Apache-2.0 and requires Node 18 or later. The canary dist-tag was still 51.7.0 from 17 April 2026, months before this feature existed, so vercel@canary is not a newer build.

Test the delete gate yourself before you trust either paragraph. Create a throwaway comment thread on a preview deployment, run vercel comments delete <thread> <message-id> --json with stdin closed, and record what happens. Until Vercel reconciles the two statements, your own observed behaviour is the only reliable specification, and it is a five-minute test.

Wrap the CLI rather than calling it directly from an agent. Vercel also ships vercel api for authenticated HTTP requests against the Vercel API, documented and dated 15 July 2026, which gives you a surface where you control the request rather than inheriting a prompt policy that changes per subcommand.

Log the results array, not the exit status, for every bulk resolve or reopen.

India-specific considerations

For Indian teams running review triage on a follow-the-sun rotation, the practical exposure is an overnight agent with delete permission acting on comments raised by a shift that has gone home. A deleted message cannot be recovered, and the thread history is often the only record of why a change was made.

Under the Digital Personal Data Protection Act 2023, comment threads on preview deployments frequently contain personal data pasted in as reproduction steps: customer emails, order IDs, screenshots of real accounts. Two consequences follow. Deletion with no confirmation and no audit trail is a weak control if you ever need to evidence what was removed and by whom, so keep the JSON response body, which for delete contains the deleted message id. And because the permissions callout on the reference page is truncated, you cannot currently establish from the documentation which team roles can delete a comment, which is exactly the kind of question an access review asks. Raise it with Vercel support rather than inferring it.

What is still unknown

Vercel has not stated which of the two delete paragraphs is authoritative, and there is no errata note on the page. The missing permissions text has no published replacement. The 2018 date has not been corrected as of 24 August 2026. Whether --yes is required, ignored or honoured in JSON mode is observable only by testing.

For related reading on the same platform, see our analysis of Vercel always-on tracing pricing and retention gaps and Vercel Connect connector secrets and revocation. The pattern is not unique to Vercel: Cloudflare's Wrangler OAuth scope documentation shipped the same kind of mismatch. Teams formalising agent permissions around a CLI should read it alongside our work on release engineering and CI/CD platforms and the web platform developer guide.

FAQ

Does vercel comments delete ask for confirmation in JSON mode?

The documentation says both things. The delete section says the command asks for confirmation by default and to pass --yes in non-interactive or JSON mode. The JSON section says JSON output does not prompt for missing input or confirmation. Vercel has not stated which is authoritative, so test it before automating.

Why is the vercel comments reference page dated 2018?

Its frontmatter reports last_updated 2018-10-20, eight years before the 20 August 2026 announcement. Neighbouring pages are dated normally: comments overview at 16 June 2026, Vercel Toolbar at 26 June 2026, managing comments at 26 February 2026. The 2018 value looks like an unfilled template default rather than a real edit date.

What does the truncated permissions callout say?

In the machine-readable Markdown rendering, the callout ends after the words "The vercel comments command" with nothing following. Vercel serves that file as text/markdown and embeds a note addressed to AI agents in it, so an agent asking which permissions delete requires finds no answer on the page.

Which vercel comments subcommands are safe to automate?

List, inspect and reply carry no irreversible action. Reply accepts standard input, so piping a commit subject into it works, and attachments are capped at 10 HTTPS URLs with no local file upload. Delete is the one to exclude from an agent's allowed commands until the prompt behaviour is confirmed.

Why does --author me fail in a CI job?

The reference states that me requires user authentication and that usernames are not supported. A pipeline authenticating with the VERCEL_TOKEN environment variable, which Vercel recommends for CI, is not user authentication. Resolve the user ID once from an interactive session and pass that ID instead of me.

How should scripts handle bulk resolve and reopen?

Bulk operations continue after an individual thread fails and exit non-zero if any operation fails, so the exit code cannot distinguish one failure from total failure. Read the JSON results array, which contains a per-thread result. Note the shape differs: a single thread returns an object with thread and replied.

What version of the Vercel CLI includes vercel comments?

The npm vercel package published 59.5.0 on 22 August 2026 under the Apache-2.0 licence, requiring Node 18 or later. The canary dist-tag was still 51.7.0 from 17 April 2026, months before this feature was announced, so installing vercel@canary does not give you the comments command.

Why does the same command return different threads on different machines?

List filters by the current Git branch when it can infer one, and branch inference applies only when the linked project matches the current checkout. Passing --project to select another project stops the branch filter applying. Pass --branch or --all-branches explicitly so the scope does not depend on the working directory.

How eCorpIT can help

eCorpIT reviews the command surfaces teams hand to AI agents, and this release is a clear example of why that review is worth an hour: an irreversible delete, a documented prompt policy that contradicts itself, and a permissions note that stops mid-sentence. Our senior engineering teams build allow-lists for agent tooling, replace ambiguous CLI calls with explicit API requests, and keep the response bodies your ISO 27001:2022 and DPDP evidence needs. If an agent in your pipeline can delete something it cannot restore, ask our platform team for an agent permissions review.

References

1. Manage Vercel Toolbar comments from the CLI — Vercel changelog, 20 August 2026.
2. vercel comments CLI reference — Vercel docs, frontmatter last_updated 20 October 2018.
3. Vercel CLI expands support for DNS, domains, and project commands — Vercel changelog, 21 August 2026.
4. vercel project CLI reference — Vercel docs, last updated 7 July 2026.
5. Comments overview — Vercel docs, last updated 16 June 2026.
6. Managing comments — Vercel docs, last updated 26 February 2026.
7. Vercel Toolbar — Vercel docs, last updated 26 June 2026.
8. vercel api CLI reference — Vercel docs, last updated 15 July 2026.
9. Vercel CLI overview, including the CI/CD environment section — Vercel docs.
10. vercel package on the npm registry — dist-tags, publish times and licence metadata, read 24 August 2026.
11. Vercel changelog index — read 24 August 2026.
12. vercel domains CLI reference — Vercel docs, last updated 15 July 2026.

Last updated: 24 August 2026.