Developer Docs

Command Reference

Complete reference of every ds CLI command with usage, flags, and descriptions.

Command Reference

This is the complete reference for every ds command. Commands are organized by category, matching the interactive menu structure.

Full automated development environment setup. Creates a fixed local stage ({developer}-local) with its own Neon database branch and Pulumi stack. Runs 11 steps: pre-flight checks, AWS SSO auth, access verification, secrets fetch, Neon branch provisioning, dependency install, Pulumi stack init, CI deploy, migrations, user seeding, and state save.

ds setup [options]

Flag	Description
`--stage <name>`	Stage name (skip interactive prompt)
`--skip-deploy`	Skip infrastructure deployment
`--skip-migrations`	Skip database migrations

`ds setup secrets pull`

Pull shared development secrets from AWS Secrets Manager to .env.

ds setup secrets pull [options]

Flag	Description
`--neon`	Also provision a Neon database branch

`ds setup secrets push`

Push local .env values to AWS Secrets Manager for other developers.

ds setup secrets push

`ds setup secrets audit`

Interactive secrets browser showing all required/optional secrets with status and guided fix prompts. Shows which secrets are configured, missing, or still at their default placeholder values, and guides you through fixing them with links to the relevant dashboards.

ds setup secrets audit

`ds help`

Show all CLI commands grouped by category.

ds help

`ds menu`

Open the interactive command menu. Same as running ds with no arguments.

ds menu

Local Development

`ds local run backend`

Start the Hono API server on port 3001 with hot reload. Runs preflight checks (tools, pnpm install, pending migrations) before starting. Auto-kills any stale process on port 3001 to prevent EADDRINUSE errors.

ds local run backend

`ds local run frontend`

Start the Vite dev server on port 8080 with HMR.

ds local run frontend

`ds local generate command`

Generate CQRS command boilerplate (command artifact, init, service handler, Lambda handler).

ds local generate command <CommandName> -m <module> [options]

Flag	Description
`-m, --module <name>`	Module name (required)
`-f, --force`	Overwrite existing files

`ds local generate query`

Generate CQRS query boilerplate.

ds local generate query <QueryName> -m <module> [options]

Flag	Description
`-m, --module <name>`	Module name (required)
`-f, --force`	Overwrite existing files

Database

`ds db current`

Show which Neon database branches your environment is currently pointing to — both the target (DB_CONNECTION_STRING) and source (SOURCE_DB_CONNECTION_STRING) databases. Resolves connection URIs to human-readable project and branch names.

ds db current

`ds db migrate`

Run pending Drizzle ORM SQL migrations. Safe to run repeatedly — already-applied migrations are skipped. Shows an interactive Neon branch picker if --db is not specified.

ds db migrate [options]

Flag	Description
`--target <stage>`	Target stage (default: `$DEVSTRIDE_STAGE`)
`--db <conn>`	Direct connection string (bypasses interactive picker)

`ds db reset`

Destructive full reset: drops all tables/schemas, terminates other DB connections, deletes all Cognito users, re-runs migrations, seeds Stripe products, and copies data from a source organization. Requires SOURCE_DB_CONNECTION_STRING to be set.

ds db reset [options]

Flag	Description
`--target <stage>`	Target stage
`-o, --organization <id>`	Source organization ID to copy
`--source-db <conn>`	Override `SOURCE_DB_CONNECTION_STRING`
`--target-db <conn>`	Override `DB_CONNECTION_STRING`

Destructive

Drops and recreates the entire database schema. Blocked on protected stages (dev, prod).

`ds db create-branch`

Create a new Neon database branch from main and update DB_CONNECTION_STRING in .env. If the branch already exists, switches .env to point to it. Restart the backend after running.

ds db create-branch [name]

`ds db delete-branch`

Delete a Neon database branch. Shows an interactive picker if no name is provided. The main branch is always protected.

ds db delete-branch [name]

`ds db list-projects`

List all Neon projects accessible with your API key.

ds db list-projects

`ds db set target-db`

Interactive Neon branch picker — writes the selected branch's connection URI to DB_CONNECTION_STRING in .env. Restart the backend after running.

ds db set target-db

`ds db set source-db`

Interactive Neon branch picker — writes the selected branch's connection URI to SOURCE_DB_CONNECTION_STRING in .env. Used to configure the data source for ds db reset.

ds db set source-db

`ds db refresh-staging`

Copy organization data from production to staging main Neon branch via GitHub Actions.

ds db refresh-staging [options]

Flag	Description
`-o, --organization <id>`	Organization ID (default: demo org)

Deployment

`ds deploy up`

Deploy infrastructure via GitHub Actions. Creates a branch-specific cloud stage ({developer}-{branch}) with its own AWS resources and Neon database branch — fully isolated from your local stage.

ds deploy up [branch] [options]

Flag	Description
`--stage <name>`	Stage name
`--branch <name>`	Branch name
`--route <label>`	DNS label / final stage name
`--new-stack`	Allow second stack for same branch

`ds deploy frontend`

Fast frontend-only deploy (~60s): builds Vue/Quasar, syncs to S3, invalidates CloudFront. No Pulumi or CI involved. Infrastructure must already be deployed.

ds deploy frontend [stage] [options]

Flag	Description
`--skip-build`	Skip build, sync existing `dist/` to S3 only

`ds deploy down`

Tear down infrastructure and clean up all resources.

ds deploy down [stage] [options]

Flag	Description
`--keep-stack`	Keep Pulumi stack state
`--delete-neon`	Also delete the Neon database branch (default: kept)
`--dry-run`	Preview without executing

`ds deploy refresh`

Run pulumi refresh to sync Pulumi state with real AWS resources. Fixes drift caused by resources deleted or modified outside Pulumi. Safe to run at any time — read-only against AWS.

ds deploy refresh

`ds deploy list`

List deployed Pulumi stages with resource details.

ds deploy list [options]

Flag	Description
`--stage <name>`	Show details for single stage
`--region <region>`	Filter by region
`--json`	Machine-readable output

API Tools

`ds api generate-api-client`

Generate typed TypeScript API client SDK from backend Hono routes.

ds api generate-api-client

Output: frontend/src/api/

`ds api generate-api-docs`

Generate OpenAPI spec with embedded documentation.

ds api generate-api-docs

Output: backend/src/modules/api/interface-adapters/lambda/http/openapi.json

Integrations

`ds integrations stripe sync-products`

Sync subscription tiers and pricing to Stripe.

ds integrations stripe sync-products

`ds integrations stripe sync-customers`

Create Stripe customers and free-tier subscriptions for organizations.

ds integrations stripe sync-customers [options]

Flag	Description
`-o, --organization <id>`	Target a single organization

`ds integrations stripe check-quantities`

Audit subscription seat counts and export CSV.

ds integrations stripe check-quantities [options]

Flag	Description
`-o, --organization <id>`	Audit a single organization

Output: subscription_quantity.csv

`ds integrations slack backfill-notifications`

Provision Slack notification workflows for all users.

ds integrations slack backfill-notifications

Utilities

`ds utils maintenance-mode enable`

Enable maintenance mode on all Lambda functions.

ds utils maintenance-mode enable

`ds utils maintenance-mode disable`

Disable maintenance mode.

ds utils maintenance-mode disable

`ds utils repair item-aggregations`

Recalculate item, board, and work type aggregations. Shows an interactive Neon branch picker before execution.

ds utils repair item-aggregations [options]

Flag	Description
`--target <stage>`	Target stage
`-o, --organization <id>`	Organization ID
`--db <conn>`	Direct connection string (bypasses branch picker)

`ds utils repair item-hierarchy`

Rebuild item hierarchy path metadata. Shows an interactive Neon branch picker before execution.

ds utils repair item-hierarchy [options]

Flag	Description
`--target <stage>`	Target stage
`-o, --organization <id>`	Organization ID
`--db <conn>`	Direct connection string (bypasses branch picker)

`ds utils repair min-max-dates`

Recalculate rolled-up start/end dates on parent items. Shows an interactive Neon branch picker before execution.

ds utils repair min-max-dates [options]

Flag	Description
`--target <stage>`	Target stage
`--db <conn>`	Direct connection string (bypasses branch picker)

`ds utils query-active-emails`

Export active user emails to CSV. Shows an interactive Neon branch picker before execution.

ds utils query-active-emails [options]

Flag	Description
`--target <stage>`	Target stage
`--db <conn>`	Direct connection string (bypasses branch picker)

Output: emails.csv, emails.txt

`ds utils delete-orphaned-items`

Delete orphaned items with cascading cleanup. Shows an interactive Neon branch picker before execution.

ds utils delete-orphaned-items [options]

Flag	Description
`--target <stage>`	Target stage
`--dry-run`	Preview without deleting
`--db <conn>`	Direct connection string (bypasses branch picker)

Irreversible

Always run with --dry-run first.

`ds utils check missing-inits`

Audit Command/Query handler registrations. Finds unregistered handlers.

ds utils check missing-inits

`ds utils check missing-correlation-ids`

Audit correlation ID usage in handlers.

ds utils check missing-correlation-ids

`ds utils check missing-event-handlers`

Audit event handler registrations (domain events, integration events, FIFO handlers, webhooks).

ds utils check missing-event-handlers

AWS Operations

`ds aws cleanup`

Discover and destroy orphaned personal stages.

ds aws cleanup [options]

Flag	Description
`--region <regions>`	Comma-separated regions to scan
`--stale-days <n>`	Days since last deploy to flag stale (default: 14)
`--dry-run`	Preview without deleting
`--include-neon`	Also delete Neon database branches
`--stages <list>`	Target specific stages
`--force`	Skip interactive confirmation

`ds aws audit`

Inventory all deployed AWS resources by stage and service.

ds aws audit [options]

Flag	Description
`--region <region>`	Scan a specific region
`--json`	Machine-readable output
`--verbose`	List individual resource names

Legacy Compatibility

These commands exist for backward compatibility with the SEED CI pipeline. They map directly to their modern equivalents.

Legacy Command	Maps To
`ds migrations run-sql`	`ds db migrate`
`ds migrations run`	`ds db migrate`
`ds script generate-api-docs`	`ds api generate-api-docs`
`ds script set-config`	Internal `set-config` function

SEED compatibility

These shims ensure the existing CI/CD pipeline continues to work during the migration from SST v2 to Pulumi. They will be removed once the migration is complete and all pipelines are updated.

AWS Operations

Discovering orphaned cloud resources, auditing AWS infrastructure, and cleaning up stale development stages.