Wavemap CLI Command Reference

This page is the curated reference home for public wavemap commands.

Use Wavemap CLI for the package boundary, command flow, and route-contract rules. Use operations pages for pipeline sequencing, approval gates, live-operation context, and runbooks.

Canonical Invocation

Durable docs should prefer the public trunk CLI form:

pnpm wavemap -- <command> [args...]

The local short alias is available for convenience:

pnpm wm -- <command> [args...]

Root package scripts remain compatibility surfaces for humans, CI, and older notes. They should be documented beside the public route they delegate to, not treated as a separate command product.

Reference Scope

Each public command entry should record:

Public pnpm wavemap -- ... route.
Root compatibility script, when one exists.
Implementation wrapper or package entrypoint.
Owner of live execution, typed planning, and command registration.
Default mutation posture.
Important options, arguments, environment overrides, and forwarded flags.
Related operations page or runbook.

Internal @wavemap/operations leaf commands are documented only when they explain file contracts, helper outputs, typed-planning boundaries, or shell-wrapper handoffs. They are not operator-facing commands unless exposed through a public route or compatibility script.

Public Vs Internal Surfaces

Use the public command surface in durable developer, operations, runbook, and workflow documentation. Internal operations surfaces may appear in implementation notes only when the reader needs to understand a typed helper contract or shell handoff.

Surface	Audience	Documentation Posture
`pnpm wavemap -- ...`	Public project command surface	Prefer in durable docs, runbooks, and operator examples.
`pnpm wm -- ...`	Local convenience alias	Mention as a shortcut, but do not make it the canonical form in durable docs.
Root compatibility scripts	Humans, CI, and older notes	Document beside the public route they delegate to. Do not describe them as a separate command product.
Shell wrappers under `bin/`	Implementation and debugging	Document as wrapper entrypoints and live-execution owners. Operators should usually reach them through `wavemap`.
`pnpm -C infra/operations operations -- ...`	Package-local typed harness	Internal and transitional. Use only for implementation debugging or focused typed-helper development.
`operations deployed-dev ...`	Typed deployed-dev helpers	Internal behind public routes and shell wrappers. Document only file contracts, helper outputs, or planning rules.
`operations docs-deploy ...`	Typed docs-deploy helpers	Internal behind public routes and shell wrappers. Document only file contracts, helper outputs, or planning rules.
`operations infra-topology ...`	Typed topology projectors	Internal behind public routes and shell wrappers. Document lower-level artifact contracts when needed.
Helper leaves such as `images-helper`, `runtime-ssm-helper`, `media-smoke-helper`, `smoke-helper`, and `publish-github-output`	Shell-wrapper helpers	Internal only. Reference them when explaining wrapper mechanics, not as commands an operator should run directly.

If a typed operation leaf becomes useful enough for routine human use, expose it through a public wavemap route or root compatibility script first, then update this reference, the route-contract tests, and any related operations page.

Command Change Convention

Command changes should move as one reviewed slice: implementation, public route contract, compatibility surface, and durable docs should stay synchronized. Do not change a wrapper flag, route name, mutation posture, or command owner and leave the reference or runbook stale for a later cleanup.

Use this convention when adding, renaming, deprecating, or removing:

A public pnpm wavemap -- ... route.
A root compatibility script.
A shell wrapper or forwarded argument.
A typed @wavemap/operations leaf that affects public command behavior.
A default mutation posture, such as dry-run versus --execute.
A GitHub workflow stage that calls one of these commands.

Change Type	Update Together
New public command	Route table in `packages/cli`, root compatibility script, route-contract test, implementation wrapper, this reference, and any operation page that explains when to use it.
Public route rename	New route, compatibility alias when needed, root script mapping, route-contract test, command examples in durable docs, and migration note if old wording remains valid.
Wrapper flag or input change	Wrapper help/usage, typed planner or parser, command reference key inputs, related runbook or workflow step, and focused wrapper/operations tests.
Default mutation posture change	Wrapper gate, typed summary wording, command reference posture, related operations/runbook approval language, workflow summary expectations, and tests that prove the new gate.
Internal typed helper change	`@wavemap/operations` parser/planner tests, shell handoff files, wrapper behavior, and public docs only if the operator-facing command surface changes.
GitHub workflow command usage change	Workflow stage, profile/resolution tests or summaries, deployment workflow docs, runbooks when operator action changes, and command reference only when the command surface changes.

Keep docs split by reader expectation:

CLI reference documents the command surface: public route, compatibility script, implementation wrapper, owner, posture, key inputs, and related docs.
Operations pages document sequencing, responsibility flow, approval gates, smoke-lane promotion, and workflow context.
Runbooks document reviewed manual procedures, recovery paths, destructive reset, rollback, and discrepancy reporting.
Working notes keep proof history, experiments, and unsettled design details until they are promoted.

Focused verification should match the changed layer:

pnpm -F @wavemap/cli test
pnpm -F @wavemap/operations test
pnpm -C apps/wavemap-docs format:check
pnpm -C apps/wavemap-docs build

Docs-only convention updates do not require CLI or operations tests. Public route or behavior changes should run the relevant package tests before being treated as ready.

Command Families

Family	Public Prefix	Compatibility Surface	Primary Wrapper Area	Related Docs
Deployed-dev deploy	`pnpm wavemap -- deploy dev ...`	`pnpm deploy:dev:*`	`bin/dev-deploy`	Deployment Workflows
Docs deploy	`pnpm wavemap -- deploy docs ...`	`pnpm deploy:docs:*`	`bin/docs-deploy`	Docs Hosting
Smoke checks	`pnpm wavemap -- smoke ...`	`pnpm smoke:*`	`bin/dev-deploy`	Testing
Infra topology	`pnpm wavemap -- infra topology ...`	`pnpm infra:topology:*`	`bin/infra-topology`	Infra Topology Processing
Local Docker control	`pnpm wavemap -- dev docker ...`	`pnpm dev:docker:*`	`bin/dev-docker`	Wavemap CLI
Application maintenance	`pnpm wavemap -- maintenance ...`	`pnpm maintenance:*`	Owning app/package	Runbooks
Private npm access	`pnpm wavemap -- npm-auth ...`	`pnpm npm-auth:*`	`bin/npm-auth`	Private npm Access

Public Route Audit

Current baseline:

The route table and its focused contract tests own the current public-route and compatibility-script inventory.
The route/script count difference is intentional: deploy dev database reset/status/migrate and transitional deploy dev db-reset/db-status/db-migrate both map to their matching deploy:dev:db-* scripts.
Compatibility scripts delegate through the matching pnpm wavemap -- ... command.
Current public routes use direct implementation commands, so trunk routes do not recurse through root package scripts.
Direct shell implementation commands point at existing wrapper files; package-owned maintenance routes identify their explicit app package entrypoint.

The key inputs column records operator-facing flags and common dispatch inputs. It intentionally omits internal helper *-out file flags unless they are useful when reproducing command behavior locally.

Application Maintenance

Public route	Compatibility script	Implementation entrypoint	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- maintenance database public-reader`	`pnpm maintenance:database:public-reader`	`pnpm -C apps/wavemap-back-end db:public-reader`	Backend Commander registration and reader reconciler	Read-only plan by default; guarded reconciliation requires `--execute`.	Mutually exclusive `--check`, `--preflight`, `--execute`; `--allow-shared-privilege-changes`; protected operator environment.	Public API Reader
`pnpm wavemap -- maintenance event media-cleanup`	`pnpm maintenance:event:media-cleanup`	`pnpm -C apps/wavemap-back-end event:cleanup-media`	Backend Commander registration and pending-cleanup owner	Dry-run by default; bounded storage deletion requires `--execute`.	`--event-public-id <id>`, `--limit <n>`, `--execute`	Runbooks
`pnpm wavemap -- maintenance event schedule-integrity report`	`pnpm maintenance:event:schedule-integrity`	`pnpm -C apps/wavemap-back-end schedule:report-integrity`	Backend Commander registration and schedule report owner	Read-only sanitized report.	`--event-public-id <id>`	Event Schedule Integrity
`pnpm wavemap -- maintenance event-series edition-integrity report`	`pnpm maintenance:event-series:edition-integrity`	`pnpm -C apps/wavemap-back-end event-series:report-edition-integrity`	Backend Commander registration and Edition report owner	Read-only sanitized report.	`--event-series-public-id <id>`, `--event-series-edition-public-id <id>`	Event Series Integrity
`pnpm wavemap -- maintenance media cleanup`	`pnpm maintenance:media:cleanup`	`pnpm -C apps/wavemap-back-end media:cleanup`	Shared backend pending-cleanup owner	Dry-run by default; bounded storage deletion requires `--execute`.	`--owner-type <type>`, `--owner-public-id <id>`, `--limit <n>`, `--execute`	Runbooks
`pnpm wavemap -- maintenance media discrepancies report`	`pnpm maintenance:media:discrepancies`	`pnpm -C apps/wavemap-back-end media:report-discrepancies`	Backend Commander registration and media report owner	Read-only sanitized report.	Entity identity scope, `--provider`, `--location`, `--prefix`, `--json`	Event Series Integrity
`pnpm wavemap -- maintenance venue mutation-receipts cleanup`	`pnpm maintenance:venue:mutation-receipts`	`pnpm -C apps/wavemap-back-end venue:cleanup-mutation-receipts`	Backend Commander registration and cleanup query owner	Dry-run by default; bounded deletion requires `--execute`.	`--retention-days <n>`, `--batch-size <n>`, `--max-batches <n>`, `--execute`	Runbooks

Private npm Authentication

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- npm-auth bootstrap`	`pnpm npm-auth:bootstrap`	`node bin/npm-auth/dispatch.mjs bootstrap`	CLI, native shell, ops	Installs/updates the native provider and user npmrc; preserves a readable token.	`--check`, `--rotate`	Private npm Access
`pnpm wavemap -- npm-auth preflight`	`pnpm npm-auth:preflight`	`node bin/npm-auth/dispatch.mjs preflight`	CLI, native shell, ops	Read-only registry proof; optionally adds a clean frozen install.	`--install`	Private npm Access
`pnpm wavemap -- npm-auth docker-proof`	`pnpm npm-auth:docker-proof`	`node bin/npm-auth/dispatch.mjs docker-proof`	CLI, native shell, ops	Expensive no-cache, no-export local image-build proof.	`--target backend-dev\|frontend-dev\|backend-deploy\|frontend-deploy`	Private npm Supply Chain

Deploy Dev

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- deploy dev preflight`	`pnpm deploy:dev:preflight`	`bin/dev-deploy/preflight-deployed-dev.sh`	Shell	Local validation only.	`--docker`	Deployment Workflows
`pnpm wavemap -- deploy dev contracts`	`pnpm deploy:dev:contracts`	`bin/dev-deploy/validate-deployed-dev-contracts.sh`	Shell plus typed ops	Local contract validation only.	`--pulumi-outputs-json <path>`	Deployment Workflows
`pnpm wavemap -- deploy dev workflow-profile`	`pnpm deploy:dev:workflow-profile`	`bin/dev-deploy/resolve-deployed-dev-workflow-profile.sh`	Typed ops via shell	Local/GitHub-output resolution only.	`--github-output`	Deployment Workflows
`pnpm wavemap -- deploy dev verify-workflow-profile`	`pnpm deploy:dev:verify-workflow-profile`	`bin/dev-deploy/verify-deployed-dev-workflow-profile.sh`	Typed ops via shell	Local verification only.	`--json`	Deployment Workflows
`pnpm wavemap -- deploy dev cloud-plan`	`pnpm deploy:dev:cloud-plan`	`bin/dev-deploy/run-deployed-dev-cloud-plan.sh`	Shell plus cloud CLIs	Read-only cloud plan.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`	Deployment Workflows
`pnpm wavemap -- deploy dev cloud-target`	`pnpm deploy:dev:cloud-target`	`bin/dev-deploy/validate-deployed-dev-cloud-target.sh`	Shell plus typed ops	Read-only caller/target validation.	`--pulumi-outputs-json <path>`, `--pulumi-stack <stack>`, `--region`, `--profile`, `--no-profile`, `--aws-account-id`, `--json`	Deployed Dev Environment
`pnpm wavemap -- deploy dev diagnostics endpoints`	`pnpm deploy:dev:endpoint-diagnostics`	`bin/dev-deploy/diagnose-deployed-dev-endpoints.sh`	Shell plus typed ops	Read-only public endpoint evidence capture.	`--app-url <url>`, `--i18n-version <version>`, `--seeded-artist`, `--seeded-artist-id <id>`, `--request-timeout-seconds <n>`, `--body-preview-bytes <n>`, `--evidence-dir <path>`	Runbooks
`pnpm wavemap -- deploy dev identity`	`pnpm deploy:dev:identity`	`bin/dev-deploy/resolve-deployed-dev-artifact-identity.sh`	Typed ops via shell	Local identity resolution only.	`--github-output`, `--output-mode text\|json\|none`, `--json`, optional identity output paths	Release And Versioning
`pnpm wavemap -- deploy dev frontend-build-inputs`	`pnpm deploy:dev:frontend-build-inputs`	`bin/dev-deploy/resolve-deployed-dev-frontend-build-inputs.sh`	Typed ops via shell	Local Pulumi-output validation only.	`--pulumi-outputs-json <path>`, `--json`	Testing
`pnpm wavemap -- deploy dev runtime-parameters`	`pnpm deploy:dev:runtime-parameters`	`bin/dev-deploy/validate-deployed-dev-runtime-parameters.sh`	Typed ops via shell	Local contract validation only.	`--pulumi-outputs-json <path>`, `--json`	Deployed Dev Environment
`pnpm wavemap -- deploy dev runtime-config plan`	`pnpm deploy:dev:runtime-config-plan`	`bin/dev-deploy/plan-deployed-dev-runtime-config.sh`	Typed ops via shell	Local plan only.	`--pulumi-outputs-json <path>`, `--json`	Deployed Dev Environment / Runbooks
`pnpm wavemap -- deploy dev runtime-config populate`	`pnpm deploy:dev:runtime-config-populate`	`bin/dev-deploy/populate-deployed-dev-runtime-config.sh`	Shell plus typed ops	Dry-run by default; writes SSM String parameters with `--execute`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--include-optional`, `--execute`	Deployed Dev Environment / Runbooks
`pnpm wavemap -- deploy dev runtime-config check`	`pnpm deploy:dev:runtime-config-check`	`bin/dev-deploy/check-deployed-dev-runtime-config.sh`	Typed ops via shell	Local inventory validation only.	`--pulumi-outputs-json <path>`, `--parameter-inventory-json <path>`, `--json`	Deployed Dev Environment / Runbooks
`pnpm wavemap -- deploy dev runtime-config live`	`pnpm deploy:dev:runtime-config-live`	`bin/dev-deploy/check-deployed-dev-live-runtime-config.sh`	Shell plus typed ops	Read-only SSM metadata check.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--parameter-prefix`, `--inventory-json-out`, `--json`	Deployed Dev Environment / Runbooks
`pnpm wavemap -- deploy dev runtime-env`	`pnpm deploy:dev:runtime-env`	`bin/dev-deploy/render-deployed-dev-runtime-env.sh`	Typed ops via shell	Local render dry-run only.	`--pulumi-outputs-json <path>`, `--runtime-deployment-source <path>`, `--json`	Deployed Dev Environment
`pnpm wavemap -- deploy dev bundle`	`pnpm deploy:dev:bundle`	`bin/dev-deploy/resolve-deployed-dev-deploy-bundle.sh`	Typed ops via shell	Local bundle resolution only.	`--pulumi-outputs-json <path>`, `--json`	Deployment Workflows
`pnpm wavemap -- deploy dev images`	`pnpm deploy:dev:images`	`bin/dev-deploy/build-images.sh`	Shell plus typed ops	Dry-run by default; Docker builds with `--execute`; ECR pushes with `--execute --push`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--image all\|backend\|frontend\|public-api`, `--frontend-env-file`, `--execute`, `--push`, `--github-output`, `--no-login`, `--no-cache`, `--buildx`, `--cache-backend`	Deployment Workflows
`pnpm wavemap -- deploy dev runtime ownership`	`pnpm deploy:dev:runtime-ownership`	`bin/dev-deploy/runtime-mutation.sh`	Shell plus typed ops	Dry plan by default; owned closure, recovery and verified reopening require `--execute`.	`--action acquire\|recover\|release\|wake\|status\|retry-transition\|reconcile-dns`, `--pulumi-outputs-json`, `--mutation-token` or `WAVEMAP_DEPLOY_MUTATION_TOKEN`, `--profile`, `--no-profile`, `--execute`.	Host Ownership
`pnpm wavemap -- deploy dev runtime deploy`	`pnpm deploy:dev:runtime`	`bin/dev-deploy/deploy-runtime.sh`	Shell plus typed ops	Dry-run by default; sends runtime SSM deploy with `--execute`.	`--pulumi-outputs-json <path>`, `--bundle-json <path>`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--document-name`, `--execute`, `--github-output`, `--no-wait`, `--wait`	Deployment Workflows / Runbooks
`pnpm wavemap -- deploy dev runtime verify-resume`	`pnpm deploy:dev:verify-runtime-resume`	`bin/dev-deploy/verify-runtime-deploy-resume.sh`	Typed ops via shell	Local resume-behavior verification only.	`--json`	Deployment Workflows
`pnpm wavemap -- deploy dev runtime record-release`	`pnpm deploy:dev:runtime-release-record`	`bin/dev-deploy/record-deployed-dev-runtime-release.sh`	Shell plus typed ops	Dry plan by default; verified host recording followed by canonical history/current publication with `--execute`.	`--pulumi-outputs-json`, `--bundle-json`, `--release-json`, `--release-store-bucket`, `--profile`, `--no-profile`, `--execute`, `--github-output`, `--wait`; live `--no-wait` refused.	Release Recovery
`pnpm wavemap -- deploy dev runtime rollback`	`pnpm deploy:dev:runtime-rollback`	`bin/dev-deploy/rollback-deployed-dev-runtime.sh`	Shell plus typed ops	Dry plan by default; restores the complete compatible release/version and republishes its receipt with `--execute`.	`--pulumi-outputs-json`, `--release-json`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--document-name`, `--record-path`, `--execute`, `--github-output`, `--wait`; live `--no-wait` refused.	Release Recovery
`pnpm wavemap -- deploy dev database reset`	`pnpm deploy:dev:db-reset`	`bin/dev-deploy/reset-deployed-dev-database.sh`	Shell plus typed ops	Dry-run by default; guarded destructive schema reset and reseed with `--execute`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--compose-file`, `--public-reader-role` or `WAVEMAP_PUBLIC_READER_ROLE`, `--allow-shared-privilege-changes`, `--execute`, `--github-output`, `--no-wait`, `--wait`	Runbooks
`pnpm wavemap -- deploy dev database status`	`pnpm deploy:dev:db-status`	`bin/dev-deploy/check-deployed-dev-database-status.sh`	Shell plus typed ops	Read-only live SSM migration status check by default; `--dry-run` prints the payload.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--compose-file`, `--dry-run`, `--github-output`	Runbooks
`pnpm wavemap -- deploy dev database migrate`	`pnpm deploy:dev:db-migrate`	`bin/dev-deploy/migrate-deployed-dev-database.sh`	Shell plus typed ops	Dry-run by default; migration-only schema mutation with `--execute`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--compose-file`, `--public-reader-role` or `WAVEMAP_PUBLIC_READER_ROLE`, `--allow-shared-privilege-changes`, `--execute`, `--github-output`, `--no-wait`, `--wait`	Runbooks
`pnpm wavemap -- deploy dev db-reset`	`pnpm deploy:dev:db-reset`	`bin/dev-deploy/reset-deployed-dev-database.sh`	Shell plus typed ops	Transitional shorthand for `deploy dev database reset`.	Same as `deploy dev database reset`.	Runbooks
`pnpm wavemap -- deploy dev db-status`	`pnpm deploy:dev:db-status`	`bin/dev-deploy/check-deployed-dev-database-status.sh`	Shell plus typed ops	Transitional shorthand for `deploy dev database status`.	Same as `deploy dev database status`.	Runbooks
`pnpm wavemap -- deploy dev db-migrate`	`pnpm deploy:dev:db-migrate`	`bin/dev-deploy/migrate-deployed-dev-database.sh`	Shell plus typed ops	Transitional shorthand for `deploy dev database migrate`.	Same as `deploy dev database migrate`.	Runbooks
`pnpm wavemap -- deploy dev media discrepancy-report`	`pnpm deploy:dev:media-discrepancy-report`	`bin/dev-deploy/report-deployed-dev-media-discrepancies.sh`	Shell plus typed ops	Dry-run by default; read-only remote report with `--execute`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--instance-id`, `--compose-file`, `--provider`, `--location`, `--prefix`, `--artist-id`, `--execute`, `--github-output`, `--no-wait`, `--wait`	Runbooks
`pnpm wavemap -- deploy dev validate-env`	`pnpm deploy:dev:validate-env`	`bin/dev-deploy/validate-deployed-dev-workflow-env.sh`	Typed ops via shell	Local/GitHub context validation only.	`--mode=skeleton`, `--mode=cloud`, `--mode=infra-topology-ingest`, `--github-context-json`	Deployment Workflows

Public API Reference

Local reference maintenance has its own docs branch. pnpm wavemap -- docs public-api generate (compatibility script pnpm docs:public-api:generate) runs bin/public-api/reference.sh generate to regenerate the versioned OpenAPI asset for review. pnpm wavemap -- docs public-api check (pnpm docs:public-api:check) runs the same wrapper in check mode and fails on drift. Both delegate schema generation to the public API application, need no runtime credentials or deployed requests, and do not publish. See Public API v1 Reference.

Deploy Docs

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- deploy docs target`	`pnpm deploy:docs:target`	`bin/docs-deploy/validate-docs-deploy-target.sh`	Typed ops via shell	Local deployment-contract validation only.	`--deployment-contract-json <path>`, `--expected-hostname`, `--github-output`, `--json`	Docs Hosting
`pnpm wavemap -- deploy docs publish`	`pnpm deploy:docs:publish`	`bin/docs-deploy/publish-docs-site.sh`	Shell plus typed ops	Dry-run by default; S3 sync and CloudFront invalidation with `--execute`.	`--deployment-contract-json <path>`, `--dist`, `--profile`, `--no-profile`, `--region`, `--cache-control`, `--invalidation-path`, `--execute`, `--skip-invalidation-wait`, `--github-output`, planning `*-out` files, `--output-mode`, `--json`	Docs Hosting

Live runtime deploy, migration/reset, record and rollback wrappers require the existing WAVEMAP_DEPLOY_MUTATION_TOKEN acquired for the complete operation. Recording and rollback also require DEPLOYMENT_CONTRACT_STORE_BUCKET (the recorder alternatively accepts --release-store-bucket); both await confirmed host success. Recording an existing --release-json in dry mode also needs the current deployment contract and store bucket to validate the publication plan. The live record path is fixed; legacy custom --record-path plans do not authorize writing another host path. See Deployment Workflows for ordering, bootstrap and interrupted-owner recovery.

Smoke

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- smoke dev`	`pnpm smoke:dev`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Endpoint HTTP smoke; optional wake/browser lanes.	`--wake`, `--seeded-artist`, `--browser-routing`, `--browser-cold-start`, `--browser-media`, `--browser-smoke`, `--browser-full`	Testing
`pnpm wavemap -- smoke dev public-api-capacity`	`pnpm smoke:dev:public-api-capacity`	`bin/public-api/capacity.sh`	Shell plus typed ops	Plan-only by default; bounded HTTP measurements with `--execute`.	`--api-url`, `--app-url`, `--output-directory`, `--main-bearer-file`, `--execute`	Public API Runtime
`pnpm wavemap -- smoke dev seeded`	`pnpm smoke:dev:seeded`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Read-only seeded endpoint smoke.	Route prewires `--seeded-artist`; accepts shared `smoke dev` flags.	Testing
`pnpm wavemap -- smoke dev media`	`pnpm smoke:dev:media`	`bin/dev-deploy/smoke-deployed-dev-media.sh`	Shell plus typed ops	Dry-run by default; temporary DB/S3 media proof with `--execute`.	`--pulumi-outputs-json <path>`, `--profile`, `--no-profile`, `--region`, `--app-url`, `--bucket`, `--artist-id`, `--execute`	Testing
`pnpm wavemap -- smoke dev browser-routing`	`pnpm smoke:dev:browser-routing`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Read-only Playwright routing smoke.	Route prewires `--browser-routing`; accepts shared `smoke dev` flags.	Testing
`pnpm wavemap -- smoke dev cold-start-browser`	`pnpm smoke:dev:cold-start-browser`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Lifecycle browser proof that exercises the wake path.	Route prewires `--seeded-artist --browser-cold-start`; accepts shared `smoke dev` flags.	Deployment Workflows
`pnpm wavemap -- smoke dev browser-media`	`pnpm smoke:dev:browser-media`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Read-only browser media delivery smoke.	Route prewires `--seeded-artist --browser-media`; accepts shared `smoke dev` flags.	Testing
`pnpm wavemap -- smoke dev browser`	`pnpm smoke:dev:browser`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Read-only seeded browser smoke.	Route prewires `--seeded-artist --browser-smoke`; accepts shared `smoke dev` flags.	Testing
`pnpm wavemap -- smoke dev e2e`	`pnpm smoke:dev:e2e`	`bin/dev-deploy/smoke-deployed-dev.sh`	Shell plus typed ops	Read-only full browser suite.	Route prewires `--seeded-artist --browser-full`; accepts shared `smoke dev` flags.	Testing
`pnpm wavemap -- smoke docs`	`pnpm smoke:docs`	`bin/docs-deploy/smoke-docs-site.sh`	Shell plus typed ops	Read-only public docs HTTP smoke.	`--base-url <url>`	Docs Hosting

Infra Topology

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- infra topology capture`	`pnpm infra:topology:capture`	`bin/infra-topology/capture-raw-pulumi-artifacts.sh`	Shell plus typed ops	Reads Pulumi backend and writes private artifacts.	`--pulumi-stack <stack>`, `--output-dir <path>`, `--environment`, `--provider`, `--pulumi-project`, `--source-ref`, `--system-components`, `--github-output`	Infra Topology Processing
`pnpm wavemap -- infra topology project-inventory`	`pnpm infra:topology:project-inventory`	`bin/infra-topology/project-sanitized-resource-inventory.sh`	Typed ops via shell	Local private-to-sanitized projection.	`--raw-capture-dir <path>`, `--output-json <path>`, `--github-output`	Infra Topology Processing
`pnpm wavemap -- infra topology project-graph`	`pnpm infra:topology:project-graph`	`bin/infra-topology/project-normalized-infra-graph.sh`	Typed ops via shell	Local normalized graph projection.	`--sanitized-inventory-json <path>`, `--dependency-edge-projection-json <path>`, `--reviewed-topology-metadata-json <path>`, `--output-json <path>`, `--github-output`	Infra Topology Processing
`pnpm wavemap -- infra topology project-diagram`	`pnpm infra:topology:project-diagram`	`bin/infra-topology/project-semantic-mermaid-diagram.sh`	Typed ops via shell	Local private diagram candidate projection.	`--normalized-graph-json <path>`, `--diagram-candidate-manifest-json <path>`, `--output-mermaid <path>`, `--manifest-json-out <path>`, `--github-output`	Infra Topology Processing
`pnpm wavemap -- infra topology render-dot`	`pnpm infra:topology:render-dot`	`bin/infra-topology/render-pulumi-dot-graph.sh`	Shell plus typed ops	Local DOT-to-SVG review artifact rendering.	`--raw-capture-dir <path>`, `--output-dir <path>`, `--github-output`	Infra Topology Processing

Dev Docker

Public route	Compatibility script	Implementation wrapper	Owner	Default posture	Key inputs / flags	Related docs
`pnpm wavemap -- dev docker up`	`pnpm dev:docker:up`	`bin/dev-docker/dev-docker-up.sh`	Shell plus Node watcher helper	Converges the backend graph without erasing retained data.	Preflights Docker and Compose before watcher work; the backend converges its retained database before readiness; streams Compose failures and diagnostics; reads local `.env.dev`; accepts `--no-cache`, `TIMEOUT_SECS`, `POLL_INTERVAL`, `SKIP_DOCKER_WATCHERS`.	Local Development
`pnpm wavemap -- dev docker stop`	`pnpm dev:docker:stop`	`bin/dev-docker/dev-docker-stop.sh`	Shell plus Node watcher helper	Stops backend/media containers and preserves named volumes.	Stops the owned background package watcher; does not inspect or stop the legacy frontend project.	Local Development
`pnpm wavemap -- dev docker down`	`pnpm dev:docker:down`	`bin/dev-docker/dev-docker-down.sh`	Shell plus Node watcher helper	Removes backend/media containers while preserving named volumes.	Stops the owned watcher and removes the unused external network; does not inspect the legacy frontend project.	Local Development
`pnpm wavemap -- dev docker reload`	`pnpm dev:docker:reload`	`bin/dev-docker/dev-docker-reload.sh`	Shell plus Node watcher helper	Rebuilds and recreates only the backend service.	Keeps the watcher and data; the recreated backend converges migrations before readiness; accepts `--no-cache`.	Local Development
`pnpm wavemap -- dev docker hard-reload`	`pnpm dev:docker:hard-reload`	`bin/dev-docker/dev-docker-hard-reload.sh`	Shell plus Node watcher helper	Exact-confirmed destructive backend/media volume recreation.	Requires `--confirm=remove-wavemap-dev-volumes`; validates the exact database target and disposable marker before stopping the watcher or removing resolved project volumes.	Local Development

Entry Shape

Use this shape when adding command entries:

### `pnpm wavemap -- deploy dev runtime deploy`

Compatibility script: `pnpm deploy:dev:runtime`

Implementation: `bin/dev-deploy/deploy-runtime.sh`

Owner: Shell owns live SSM execution; `@wavemap/operations` owns typed planning helpers.

Default posture: Dry-run by default. Live runtime mutation requires `--execute`.

Key options: `--pulumi-outputs-json`, `--profile`, `--no-profile`, `--region`, `--execute`, `--github-output`,
`--no-wait`, `--wait`.

Related docs: [Deployment Workflows](/operations/deployment-workflows/)

Maintenance Rule

When a public route, root compatibility script, wrapper flag, default mutation posture, or route ownership changes, update this reference and any linked operations or runbook page in the same documentation pass. The Command Change Convention is the checklist for deciding which implementation, test, and docs surfaces move together.