Skip to content

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

Open
crowlbot wants to merge 1 commit into
mainfrom
feat/agent-help-text
Open

feat(help): mention agent / CI conventions in root --help#100
crowlbot wants to merge 1 commit into
mainfrom
feat/agent-help-text

Conversation

@crowlbot
Copy link
Copy Markdown
Contributor

@crowlbot crowlbot commented Jun 1, 2026

Summary

Make deno deploy --help itself surface the agent/CI conventions that landed in #91-#95. Today the global --json, --non-interactive, --token and the DENO_DEPLOY_TOKEN env var are all individually documented in --help line items, but the root command description gives no hint that they exist as a coherent agent-mode contract or that there's a stable exit-code taxonomy.

Tiny change:

  • deploy/mod.ts — expand deployCommand.description() to mention DENO_DEPLOY_TOKEN, the recommended --json --non-interactive invocation, the exit-code taxonomy (0–6), and the structured error envelope. Link to docs.deno.com/runtime/reference/cli/deploy/#agent--ci-usage for the full reference.
  • deploy/mod.ts — add three .example() entries for the most common agent flows: whoami --json, non-interactive publish, non-interactive create.
  • sandbox/mod.ts — expand sandboxCommand.description() to document the DENO_DEPLOY_TOKEN escape hatch and link to the sandbox reference. (Intentionally does not advertise --json / --non-interactive for sandbox, because the standalone deno sandbox command doesn't currently expose those as globals — a separate gap for a follow-up.)

Why root-description and not per-subcommand

--help listings are dense; per-flag descriptions don't compose into a story about "how do I drive this from a bot." A 6-line prose paragraph at the top of the root command's description is the natural place to set that context, alongside a few .example() entries that the agent can pattern-match.

Test plan

deno fmt, deno lint, deno check main.ts, deno test -A — CI runs all four. No behavior change; only --help text.

Companion

The canonical reference URL this links to is being added in denoland/docs#3180.

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.
@crowlbot
Copy link
Copy Markdown
Contributor Author

crowlbot commented Jun 1, 2026

The remaining deno CI failure is the known sandbox-backend flake, not anything in this diff (the changes are text-only — root-command description strings and three .example() entries).

The sandbox copy and sandbox copy directory structure tests have failed on every re-run today with backend errors (SANDBOX_WEBSOCKET_HANDSHAKE_ERROR / DEPLOYMENT_NOT_FOUND / INTERNAL_SERVER_ERROR), same pattern as the other open PRs (#98, #99) and as recent main runs occasionally do. jsr, fmt, lint, check and the other 31 tests all pass.

Happy to re-run once more if you'd like to wait for green, otherwise this should be safe to admin-merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants