feat(help): mention agent / CI conventions in root --help

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,

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,