Deploy CLI deficiencies and missing-feature roadmap

## 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). Originally written against `main` @
`2c7421b` (`@deno/deploy@0.0.99`); last updated 2026-07-02 after the bug-fix /
CI-hardening triage (see "Completed" at the bottom).

This is meant as a tracking/roadmap issue. Current state: the confirmed-bug
backlog and the CI/agent rough edges are **done and shipped in
`@deno/deploy@0.0.9902`**; what remains is the feature-parity backlog in
section 3.

## 1. Current command surface (0.0.9902)

```
deno deploy [root-path|file] deploy dir (a file positional deploys its parent dir)
create interactive or fully-flagged (local/github, static/dynamic)
env list|add|update-value|update-contexts|delete|load (all emit JSON under --json)
database provision|link|assign|detach|query|list|delete (all emit JSON under --json)
apps list|get get exposes productionUrl/domains/timelines
orgs list | deployments list
logs live stream, [--start/--end], or --once; NDJSON with --json
setup-aws | setup-gcp scriptable via --policies/--roles/--role-name/--enable-apis/--apply
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 --endpoint
```

Plus `AGENTS.md` documenting the whole non-interactive/agent contract.

## 2. Confirmed bugs still on `main`

None — everything from the original table is fixed (see "Completed").

Residual test-coverage gaps: the `database` and `switch` commands and the
`orgs`/`apps`/`deployments` listings still have no live test coverage (env,
publish `--json`, CLI contract, config persistence, sandbox create, and the
rs_lib collector all gained tests during the triage). Note also that the live
sandbox tests intermittently flake on backend 5xx
(`SANDBOX_WEBSOCKET_HANDSHAKE_ERROR`) — retry the job when that happens.

## 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` + `apps get`; no delete/rename/settings) |
| 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; bounded capture via `--once`) |
| Custom domains: add, verify DNS, TLS provision/upload, attach/detach | Y | Y | N |
| Databases / KV / Prisma / external SQL | Y | Y | Y |
| 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**
- Cut the next release with the triage fixes below.
- Verify `--prod` promotion reliability (the one part of the original P0 not
yet independently confirmed fixed).

**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` mutations: `delete`, `cancel`, app `rename`/settings.
- 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 (#81).

## Completed (2026-07-02 triage)

All confirmed bugs and CI/agent rough edges from the original issue, landed on
`main`:

- #104 `database link` unusable (crash, string port, payload key) — #105, hardened further in #117
- #90 workspace-root `deploy.include` stripped member files — #99 (proper fix: `deno_config` 0.103 bump, upstream denoland/deno#34788)
- denoland/deno#33365 Windows `(os error 123): readfile '/C:/...'` — #89
- #123 Windows `deploy.include` collected zero files — #124
- `authedFetch` broke when `DENO_DEPLOY_ENDPOINT` contains a path — #82
- #103 persisting org/app clobbered sibling `deploy.*` fields — #103
- #108 production URL not machine-readable; `--no-wait --json` empty — #121 (`apps get`, `productionUrl` in deploy JSON)
- #106 KV connect database id not exposed — #117 (`databaseId` + `connectUrl` in `database list --json`)
- #107 positional file treated as config file — #114
- Deploy process hung until CI timeout after success — #125, #121 (ProgressBar)
- `sandbox create` hung forever in CI (session keep-alive) — #118
- `--json` stdout pollution in env/database/switch/setup wizards — #119, #117, #116, #115
- Exit code 2 (USAGE) + JSON envelope for bad flags — #116
- `setup-aws`/`setup-gcp`: error envelope, `--apply` confirmation gate, no silent infra mutation — #115
- `logs --once` bounded non-interactive capture — #120
- Success/status chrome routed to stderr CLI-wide — #122
- `AGENTS.md` non-interactive/agent reference — #110
- Tests: CLI exit-code contract, env `--json`, config persistence, sandbox fail-fast, rs_lib regressions now run via `cargo test` in CI — #111, #116, #119, #103, #118, #128
- Issues closed as fixed: #79 (env load in CI), #104, #106, #107, #108, #90, #123

## References

- This repo: #81 (open); #70 (sandbox quickstart) and #77 (sandbox dashboard TUI) closed as not planned.
- `denoland/deno`: #31113, #31699, #32101, #32197, #32199, #32236, #32436, #32875, #33365, #35181.
- Public API: https://api.deno.com/v2/docs