From 26a47365142b620514c0c604ecdacf9b8af0a5cc Mon Sep 17 00:00:00 2001
From: crowlbot <280062030+crowlbot@users.noreply.github.com>
Date: Mon, 1 Jun 2026 16:01:29 +0000
Subject: [PATCH] feat(help): mention agent / CI conventions in root --help

Expand the deno deploy root description so deno deploy --help itself
points users at DENO_DEPLOY_TOKEN, --json + --non-interactive, the exit
code taxonomy, and the canonical reference page on docs.deno.com.

Add three .example() entries to the deploy command for the most common
agent flows: whoami, non-interactive publish, non-interactive create.

For deno sandbox, the standalone command does not yet wire up --json /
--non-interactive globally, so the description only documents the
DENO_DEPLOY_TOKEN escape hatch and points at the docs reference.
---
 deploy/mod.ts  | 22 +++++++++++++++++++++-
 sandbox/mod.ts |  7 ++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/deploy/mod.ts b/deploy/mod.ts
index a409722..266c832 100644
--- a/deploy/mod.ts
+++ b/deploy/mod.ts
@@ -300,7 +300,27 @@ export const deployCommand = new Command()
   .description(`Interact with Deno Deploy
 
 Calling this subcommand without any further subcommands will
-deploy your local directory to the specified application.`)
+deploy your local directory to the specified application.
+
+For non-interactive use (CI, AI agents), authenticate via the
+DENO_DEPLOY_TOKEN env var (or --token) and pass --json --non-interactive
+to every subcommand. The CLI then emits a single JSON object on stdout,
+a structured { error: { code, message, hint } } envelope on stderr,
+and a stable exit code (0 OK, 1 GENERIC, 2 USAGE, 3 AUTH, 4 NOT_FOUND,
+5 CONFLICT, 6 NETWORK). See https://docs.deno.com/runtime/reference/cli/deploy/#agent--ci-usage
+for the full reference.`)
+  .example(
+    "Verify the active token",
+    "whoami --json",
+  )
+  .example(
+    "Deploy current directory non-interactively",
+    "--json --non-interactive --org my-org --app my-app --prod",
+  )
+  .example(
+    "Create a static app from CI",
+    "create --json --non-interactive --org my-org --app my-app --source local --runtime-mode static --static-dir dist --region us",
+  )
   .globalOption("--endpoint <endpoint:string>", "the endpoint", {
     default: "https://console.deno.com",
     hidden: true,
diff --git a/sandbox/mod.ts b/sandbox/mod.ts
index cf2b8c3..1277813 100644
--- a/sandbox/mod.ts
+++ b/sandbox/mod.ts
@@ -590,7 +590,12 @@ Example:
 export const sandboxCommand = new Command<GlobalContext>()
   .name("deno sandbox")
   .version(VERSION)
-  .description("Interact with sandboxes")
+  .description(`Interact with sandboxes
+
+For headless / CI use, authenticate via the DENO_DEPLOY_TOKEN env var
+(or --token) — no browser flow is opened when a token is supplied.
+See https://docs.deno.com/runtime/reference/cli/sandbox/ for the
+full reference.`)
   .globalOption("--endpoint <endpoint:string>", "the endpoint", {
     default: "https://console.deno.com",
     hidden: true,