Deploy CLI deficiencies and missing-feature roadmap

[piscisaureus]

Summary

A review of the CLI against open issues (here and in denoland/deno), recurring
user reports, and a feature-parity comparison with the web dashboard and the
public API (https://api.deno.com/v2/docs). Baseline: main @ 2c7421b
(@deno/deploy@0.0.99).

This is meant as a tracking/roadmap issue. Findings are grouped into: ship what's
already built, confirmed bugs, remaining CI/agent rough edges, and missing
feature areas.

0. A finished overhaul is unreleased

The CI / AI-agent readiness work that landed on main (#86, #91–#102) is not yet
released, so the version most users run is the older CLI. Releasing it resolves a
large share of common complaints by itself:

• --debug now defaults to false (previously noisy + wrote a debug tarball on every deploy)
• global --json, NDJSON logs, --non-interactive/-y, -q/--quiet
• structured error envelope { error: { code, message, hint, traceId } } and exit-code taxonomy (0 OK, 1 GENERIC, 2 USAGE, 3 AUTH, 4 NOT_FOUND, 5 CONFLICT, 6 NETWORK) — replaces the old opaque "internal error + trace id" output that is the single most common CLI complaint
• new commands: whoami, apps list, orgs list, deployments list, database *, switch, --version
• --ignore file exclusion (addresses denoland/deno#31113), static-app create flow (addresses denoland/deno#32236), scriptable setup-aws/setup-gcp

Action: cut the release tracked in #109. Highest-leverage single step.

1. Current command surface (v0.0.99)

deno deploy [root-path]        deploy current dir
  create                       interactive or fully-flagged (local/github, static/dynamic)
  env       list|add|update-value|update-contexts|delete|load
  database  provision|link|assign|detach|query|list|delete
  apps list | orgs list | deployments list
  logs                         live stream or [--start/--end]; NDJSON with --json
  setup-aws | setup-gcp        scriptable via --policies/--roles/--role-name/--enable-apis
  switch | whoami | logout
  sandbox   create|list|kill|ssh|exec|extend|deploy|copy|volumes|snapshot
Global: --json -q/--quiet -y/--non-interactive --ignore --token --config --org --app --prod --no-wait --debug

2. Confirmed bugs still on main

Issue	Bug	Notes
#104	database link unusable: --hostname is required: true and options declare conflicts: ["connectionString"], but connectionString is a positional arg, so the two documented forms are mutually unreachable; --port is passed as a string.	PR #105
#90	deploy.include from a workspace root collects no workspace-member files.	PR #99
denoland/deno#33365	Windows path error (os error 123): readfile '/C:/...'.	PR #89
—	authedFetch URL resolution breaks when DENO_DEPLOY_ENDPOINT contains a path.	PR #82
#103	Persisting org/app rewrites/loses other deploy.* fields and prints Created configuration file… to stdout (pollutes --json).	PR #103
#108	Production app URL not exposed machine-readably. --json deploy emits revisionId, a url (the builds page, not the app URL), and timelines[].domains, but no explicit productionUrl; and --no-wait --json emits empty stdout (no revision id).
#106	database list exposes only a generated clientId for Deno KV, not the connect database ID needed for openKv.
#107	A positional file argument is treated as a config path rather than a deploy root.
#55	No cache-invalidate subcommand.	PR #64

Remaining CI / agent rough edges in current code

• sandbox create --json blocks forever in non-interactive/CI: the default timeout=session installs a SIGINT keep-alive with no TTY/--non-interactive guard; the JSON/exit path only runs for non-session timeouts.
• --json stdout pollution: env add/update/delete, all database mutations, switch, and the setup-aws/setup-gcp wizards print human text to stdout and never emit a JSON result, corrupting piped output.
• Exit code 2 (USAGE) is not actually delivered for bad flags — Cliffy ValidationError exits 1; code 2 only fires on the CLI's own requireInteractive/missing-flag paths.
• setup-aws/setup-gcp bypass the error envelope on cancel / missing external CLI using bare Deno.exit(1); agents get no JSON envelope or stable code.
• setup-* auto-applies infra (creates IAM roles / service accounts) under --non-interactive with no confirmation.
• logs has no --once/tail-then-exit for bounded non-interactive capture without --end.
• Thin tests: the publish/deploy --json success envelope, --no-wait --json, the entire database command, env subcommands, switch, orgs/apps/deployments, and the sandbox create hang are untested.

3. Feature parity vs dashboard / public API

The guiding principle: anything you can do in the dashboard or via the public
API should be doable from the CLI — independent of whether a user has filed a
ticket for it. Many of the gaps below have no associated report; they are listed
because completeness (and scriptability/IaC) requires them.

A concrete example with no ticket behind it: custom timelines. The dashboard
can create, update, and delete named deployment timelines (e.g. production,
preview, per-branch or per-environment targets) and route revisions/domains to
them. The public API only exposes this read-only
(GET /v2/revisions/{revision}/timelines reports the timelines a revision
serves) — there is no create/update/delete — and the CLI has no timelines
command at all, so this entire named-environment workflow is unscriptable today. Other completeness-only gaps in
the same vein: layers (shared env/config across apps), rate limits /
firewall (WAF), cron management, org members & roles, token CRUD,
and cloud-connection list/test/delete.

Legend: Y available, P partial, N none.

Area	Dashboard	API	CLI
Deploy / create (local + GitHub, static/dynamic)	Y	Y	Y
App listing / inspect	Y	Y	P (apps list only)
App settings: rename, delete, regions, memory/runtime limits, build timeout	Y	Y	N
Rollback / promote (redeploy a prior revision)	Y	Y	N — frequently requested; --prod does not reliably promote and there is no workaround
Deployment/revision listing	Y	Y	P (deployments list; no cancel/delete/restart)
Build logs streaming	Y	Y	N (CLI streams runtime logs only) — common ask when builds fail with no usable output
Runtime logs	Y	Y	Y (NDJSON)
Custom domains: add, verify DNS, TLS provision/upload, attach/detach	Y	Y	N
Databases / KV / Prisma / external SQL	Y	Y	Y (see #104, #106)
Cron jobs: list, inspect, invoke, enable/disable	Y	N	N
Metrics / analytics / traces (OTEL)	Y	Y	N — common ask for programmatic/OTEL access
Custom timelines (create/update/delete named deployment environments; route revisions and domains to them)	Y	N (read-only: GET /v2/revisions/{revision}/timelines; no create/update/delete)	N — no ticket; needed for parity and IaC
Tunnels	Y	N	N (only hidden tunnel-login)
Rate limits / firewall (WAF)	Y	N	N
GitHub build integration: link repo, branches, trigger build, build config	Y	N	P (create can link a repo)
Org members / access control	Y	N	N
Org settings: rename, slug, OTel exporter	Y	P	N
Tokens CRUD (personal + org access tokens)	Y	N	N (only login/logout/whoami)
Billing / quotas / spend limits	Y	N	N
Layers (shared env/config)	Y	Y	N
Sandboxes (+ volumes / snapshots)	Y	N	Y
Code Explorer / Playground	Y	N	N
Cloud connections (AWS/GCP)	Y	N	P (setup only; no list/test/delete)
OIDC deployments (keyless CI auth)	P	—	N — #81
Classic to new migration (projects + env + KV)	P	—	N — frequently requested
Account management	Y	N	N

4. Prioritized roadmap

P0 — ship and stabilize

• Cut the release (Cut a new deploy-cli release for JSON/non-interactive commands #109).
• Merge ready fix PRs: fix(database): make database link usable (crash + port type + payload key) #105, fix(rs_lib): restore stripped deploy.include for workspace-member paths #99, fix: (os error 123): readfile '/C:/path/to/project/index.ts' #89, fix: authedFetch URL resolution breaks when DENO_DEPLOY_ENDPOINT contains a path #82, fix(config): preserve other deploy fields when writing org/app #103.
• Fix the sandbox create --json CI hang and the --json stdout pollution in env/database/switch/setup (route human text to stderr; emit JSON).
• Fix --prod promotion; emit an explicit productionUrl in deploy JSON; emit JSON under --no-wait (Expose an app's production URL in a machine-readable CLI command #108).

P1 — highest-demand feature gaps

• Custom domains (add/verify/TLS-provision/attach).
• Build logs (deployments build-logs / logs --build).
• Rollback / promote (deployments promote|rollback).
• apps/deployments beyond list: get/inspect, delete, cancel; app delete/rename/settings.
• cache-invalidate (deno deploy cache-invalidate subcommand #55 / PR feat: cache subcommand #64) and a Classic to new migrate command.
• Token CRUD (tokens create/list/revoke).

P2 — full parity (largely completeness-driven, not ticket-driven)

• Custom timelines (timelines create|update|delete, route revisions/domains to named environments).
• Layers (shared env/config across apps).
• Cron management, metrics/analytics/traces (OTEL), org members & settings, billing/quotas, rate-limits/firewall, cloud-connection list/test/delete, sandbox volume/snapshot fixes, tunnels, OIDC deployments (OIDC deployments? #81).

References

• This repo: deno deploy cache-invalidate subcommand #55, Unable to always load env file in CI #79, OIDC deployments? #81, deploy.include from workspace root collects no workspace member files #90, database link crashes: Unknown conflicting option "connectionString" #104, Expose Deno KV connect database IDs in database list #106, Treat positional file arguments as deploy roots, not config files #107, Expose an app's production URL in a machine-readable CLI command #108, Cut a new deploy-cli release for JSON/non-interactive commands #109; PRs feat: cache subcommand #64, feat: deno sandbox quickstart #70, sandbox dashboard #77, fix: authedFetch URL resolution breaks when DENO_DEPLOY_ENDPOINT contains a path #82, fix: (os error 123): readfile '/C:/path/to/project/index.ts' #89, fix(rs_lib): restore stripped deploy.include for workspace-member paths #99, fix(config): preserve other deploy fields when writing org/app #103, fix(database): make database link usable (crash + port type + payload key) #105, docs: add AGENTS.md for non-interactive / agent usage #110, test: cover publish flow non-interactive --json output #111.
• denoland/deno: #31113, #31699, #32101, #32197, #32199, #32236, #32436, #32875, #33365, #35181.
• Public API: https://api.deno.com/v2/docs