Introduction to the ds CLI

The ds command-line interface is the central tool for DevStride development. It handles everything from initial environment setup to deploying infrastructure, managing databases, running local servers, and maintaining production systems. Rather than memorizing a dozen different tools and scripts, you interact with a single, consistent interface.

What ds Does

The CLI wraps and orchestrates the tools in the DevStride stack:

• AWS (SSO authentication, Lambda, S3, Cognito, Secrets Manager)
• Pulumi (infrastructure-as-code deployments)
• Neon (PostgreSQL database branching)
• GitHub Actions (CI/CD pipeline dispatch)
• Stripe (subscription and customer management)
• Slack (notification provisioning)
• Hono + Vite (local backend and frontend dev servers)

Instead of running raw pulumi up, aws secretsmanager get-secret-value, or gh api commands manually, ds provides purpose-built commands that encode DevStride's conventions, guard against mistakes, and automate multi-step workflows.

Architecture at a Glance

ds <command> [subcommand] [options]
│
├── cli/run_script.sh          ← Shell entry point, compiles TS on-the-fly
├── cli/commands/
│   ├── command-registry.ts    ← Central registry of all commands
│   ├── setup.ts               ← ds setup
│   ├── db.ts                  ← ds db *
│   ├── deploy.ts              ← ds deploy *
│   ├── infra/run.ts           ← ds local run *
│   ├── api.ts                 ← ds api *
│   ├── integrations.ts        ← ds integrations *
│   ├── utils.ts               ← ds utils *
│   └── aws.ts                 ← ds aws *
└── cli/helpers/               ← Shared utilities (prompts, Neon client, AWS wrappers)

Commands are TypeScript files compiled with esbuild at runtime. The command registry (command-registry.ts) is the single source of truth for every command's name, description, and help text.

Core Concepts

Stages

A stage is an isolated, fully deployed copy of DevStride — its own API Gateway, Lambda functions, S3 bucket, Cognito user pool, DynamoDB tables, and DNS records. Every developer gets their own personal stage(s).

• Protected stages: dev and prod are shared environments with safeguards against destructive operations.
• Local stage: Named {developer}-local (e.g., phil-local). A fixed stage for local development that never changes regardless of your git branch. Created by ds setup.
• Cloud stages: Named {developer}-{branch} (e.g., phil-feature-auth). Branch-specific stages for cloud testing. Created by ds deploy up.
• URLs follow a predictable pattern:
  • API: https://api-{stage}.devstride.dev
  • UI: https://app-{stage}.devstride.dev
  • Exception: dev and prod use the bare domain (api.devstride.dev, app.devstride.dev).

Local vs. Cloud Stages

DevStride uses two stage models:

• Local stage ({developer}-local): Fixed, branch-independent. Used by ds local run, ds db, and all local commands. Switching git branches does not change your local stage — your bind cache, Neon database, and Pulumi stack remain stable.
• Cloud stages ({developer}-{branch}): Branch-aware, created on demand by ds deploy up. Each feature branch can have its own isolated cloud environment for testing.

The ./ds wrapper computes DEVSTRIDE_STAGE as {developer}-local on every invocation, so local commands always target a stable environment.

Protected Stage Guards

Destructive commands (db reset, deploy down, aws cleanup) are blocked on protected stages (dev, prod). Even with --force, these stages require explicit developer verification. This prevents accidental data loss in shared environments.

AWS SSO Session Guard

Commands that require AWS credentials automatically check your SSO session. If your token has expired, the CLI triggers a re-login before proceeding — no more cryptic "credentials expired" errors halfway through a deployment.

The Interactive Menu

Running ds with no arguments (or ds menu) opens an interactive menu:

$ ds

  DevStride CLI

  ❯ Local Development
    Database
    Deployment
    API Tools
    Integrations
    Utilities
    AWS Operations
    Setup & Config

  ↑↓ Navigate  ⏎ Select

The menu provides a curated view of common commands with descriptions. It's the fastest way to discover what's available without memorizing command names.

Getting Help

# Show all commands grouped by category
ds help

# The interactive menu with descriptions
ds menu

# Check your environment health
ds doctor

ds doctor runs diagnostic checks across three categories:

Each check shows a color-coded status: + pass, ✗ fail, ○ warning. Run ds doctor whenever something feels off — it's the fastest way to diagnose environment issues.

Next Steps

If you're setting up for the first time, continue to Getting Started for the full setup walkthrough.

If you're already set up and want to understand the day-to-day workflow, skip to Developer Lifecycle.