#CLI Commands

The tsdevstack CLI handles project management, code generation, and deployment workflows.

#Installation

The CLI is installed as a project devDependency (@tsdevstack/cli). Run commands with npx tsdevstack (or npx tsds) from your project root.

npx tsdevstack --version
npx tsdevstack --help

#Local Development Commands

#sync

Regenerate all framework-managed configuration files. This is the most frequently used command.

npx tsdevstack sync

What it generates:

• kong.tsdevstack.yml - Gateway routes from OpenAPI specs
• docker-compose.yml - Container orchestration with injected secrets
• .secrets.tsdevstack.json - Framework secrets
• .secrets.local.json - Merged secrets for local development

When to run:

• After adding or removing services
• After changing OpenAPI decorators
• After modifying .tsdevstack/config.json
• After pulling changes that modify service structure

#add-service

Add a new application to the monorepo.

npx tsdevstack add-service --name <name> --type <type>

Types:

Example:

npx tsdevstack add-service --name payments-service --type nestjs
npx tsdevstack add-service --name web-app --type nextjs
npx tsdevstack add-service --name dashboard --type spa

#remove-service

Remove a service from the local project.

npx tsdevstack remove-service [service-name]

Removes the service directory and updates .tsdevstack/config.json. If no service name is provided, prompts for selection.

#generate-kong

Generate Kong gateway configuration from OpenAPI specs.

npx tsdevstack generate-kong

Generates kong.tsdevstack.yml with exact routes derived from your service OpenAPI specifications, merges it with kong.user.yml into kong.yml, and writes the gateway image build context in infrastructure/kong/ (generated Dockerfile, .dockerignore, and a staged copy of the framework plugins and your kong-plugins/). Rebuild the gateway afterwards with docker compose up -d --build gateway, or use sync, which does both. See Kong Plugins.

Partner services get the API key check and the per-IP ceiling (framework.apiKeys.ipLimitPerMinute in .tsdevstack/config.json); the default key limits are copied from the global rate-limiting in kong.user.yml. It warns about consumers with keyauth_credentials in kong.user.yml, which no longer work. See API Keys.

#generate-secrets

Generate secrets for local development.

npx tsdevstack generate-secrets

Creates:

• .secrets.tsdevstack.json - Framework-generated secrets (JWT keys, database passwords, etc.)
• .secrets.user.json - Your custom secrets (preserved across regeneration)
• .secrets.local.json - Merged result used by docker-compose

#generate-docker-compose

Generate docker-compose.yml with injected secrets.

npx tsdevstack generate-docker-compose

#generate-client

Generate TypeScript API client from OpenAPI spec.

npx tsdevstack generate-client [service-name]

Creates a typed API client package in packages/ that frontends can import.

#validate-service

Validate a service follows naming conventions and structure.

npx tsdevstack validate-service [service-name]

#Worker Commands

#register-detached-worker

Register a worker for separate container deployment.

npx tsdevstack register-detached-worker --name <worker-name> --base-service <service-name>

#unregister-detached-worker

Remove a detached worker registration.

npx tsdevstack unregister-detached-worker --worker <worker-name>

#Storage Commands

#add-bucket-storage

Add an object storage bucket to the project.

npx tsdevstack add-bucket-storage --name <name>

What it does:

• Adds bucket to storage.buckets in config.json
• Regenerates docker-compose.yml with MinIO (first bucket adds MinIO container + minio-init job)
• Regenerates secrets with STORAGE_ENDPOINT, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY, STORAGE_BUCKET_{NAME}

Options:

Example:

npx tsdevstack add-bucket-storage --name uploads
npx tsdevstack add-bucket-storage --name media-assets

After adding, run docker compose up -d to start MinIO. Console at http://localhost:9001 (minioadmin/minioadmin).

#remove-bucket-storage

Remove a storage bucket from the project.

npx tsdevstack remove-bucket-storage [--name <name>]

Removes the bucket from config.json and regenerates docker-compose and secrets. If no name is provided, prompts for selection. Does not delete local MinIO data or cloud resources.

Options:

#Messaging Commands

#add-messaging-topic

Add an async messaging topic to the project.

npx tsdevstack add-messaging-topic --name <name> --publishers <services> --subscribers <services>

What it does:

• Adds topic to messaging.topics in config.json
• Validates name (kebab-case, no duplicates)
• Validates publisher/subscriber service names exist and are NestJS type
• Runs sync

Options:

Example:

npx tsdevstack add-messaging-topic --name user-created --publishers auth-service --subscribers offers-service,notifications-service

#remove-messaging-topic

Remove a messaging topic from the project.

npx tsdevstack remove-messaging-topic [--name <name>]

Removes the topic from config.json and runs sync. Does not delete stream data in Redis.

Options:

#update-messaging-topic

Update publishers and subscribers for an existing topic.

npx tsdevstack update-messaging-topic --name <name> --publishers <services> --subscribers <services>

Options:

#Cloud Secrets Commands

#cloud:init

Initialize cloud secrets provider integration.

npx tsdevstack cloud:init --gcp    # or --aws, --azure

#cloud-secrets:push

Push local secrets to cloud environment.

npx tsdevstack cloud-secrets:push --env <environment>

#cloud-secrets:diff

Compare local and cloud secrets.

npx tsdevstack cloud-secrets:diff --env <environment>

#cloud-secrets:set

Set or update a secret in cloud.

npx tsdevstack cloud-secrets:set <key> [value] --env <environment>

#cloud-secrets:get

Get a secret value from cloud.

npx tsdevstack cloud-secrets:get <key> --env <environment>

#cloud-secrets:list

List all secrets in cloud environment.

npx tsdevstack cloud-secrets:list --env <environment>

#cloud-secrets:remove

Remove a secret from cloud.

npx tsdevstack cloud-secrets:remove <key> --env <environment>

#Infrastructure Commands

All infrastructure commands use the infra: prefix and require cloud credentials (except CI commands — see below).

Note: Environment names (e.g., dev, staging, prod) are user-defined based on your cloud credentials configuration. The framework does not enforce specific environment names.

#infra:bootstrap

Bootstrap GCP project (enable APIs, add roles to service account).

npx tsdevstack infra:bootstrap --env <environment>

#infra:init

Initialize infrastructure (creates Terraform state bucket).

npx tsdevstack infra:init --env <environment>

#infra:generate

Generate Terraform files.

npx tsdevstack infra:generate --env <environment>

With the auth template, it warns when the environment's scheduledJobs lack the sync-api-key-usage job and prints the entry to add. See API Keys.

#infra:plan

Show planned infrastructure changes.

npx tsdevstack infra:plan --env <environment>

#infra:deploy

Deploy full infrastructure: base + services + Kong + load balancer.

npx tsdevstack infra:deploy --env <environment>

#infra:destroy

Destroy infrastructure.

npx tsdevstack infra:destroy --env <environment>

#infra:deploy-service

Build, push, and deploy a single service.

npx tsdevstack infra:deploy-service [service-name] --env <environment>

#infra:deploy-services

Build, push, and deploy all services in parallel.

npx tsdevstack infra:deploy-services --env <environment>

#infra:remove-service

Remove a service from cloud (deletes Cloud Run, secrets, database, etc.).

npx tsdevstack infra:remove-service [service-name] --env <environment>

#infra:deploy-kong

Deploy Kong Gateway to Cloud Run.

npx tsdevstack infra:deploy-kong --env <environment>

#infra:deploy-lb

Deploy External HTTP(S) Load Balancer for Kong Gateway.

npx tsdevstack infra:deploy-lb --env <environment>

#infra:init-ci

Initialize CI/CD (generates GitHub Actions workflows). No cloud credentials required.

npx tsdevstack infra:init-ci
npx tsdevstack infra:init-ci --envs dev,prod

Options:

#infra:generate-ci

Regenerate CI workflows from ci.json. No cloud credentials required.

npx tsdevstack infra:generate-ci

#infra:status

Check infrastructure configuration status.

npx tsdevstack infra:status --env <environment>

#infra:list-deployed

List all deployed services in an environment.

npx tsdevstack infra:list-deployed --env <environment>

#infra:service-status

Check cloud resource status for a specific service.

npx tsdevstack infra:service-status [service-name] --env <environment>

#Database Migration Commands

#infra:plan-db-migrate

Show pending database migrations for a service.

npx tsdevstack infra:plan-db-migrate --service <service-name> --env <environment>

The --service flag is required. It specifies which service's database to check.

#infra:run-db-migrate

Apply pending database migrations.

npx tsdevstack infra:run-db-migrate --service <service-name> --env <environment>

The --service flag is required. It specifies which service's database to migrate.

#Scheduled Jobs Commands

The scheduler commands work across all providers, but each provider uses a different underlying service:

#infra:deploy-scheduler

Deploy a single scheduled job.

npx tsdevstack infra:deploy-scheduler --job <job-name> --env <environment>

#infra:deploy-schedulers

Deploy all scheduled jobs.

npx tsdevstack infra:deploy-schedulers --env <environment>

#infra:list-schedulers

List scheduled jobs and their deployment status.

npx tsdevstack infra:list-schedulers --env <environment>

#infra:remove-scheduler

Remove a scheduled job.

npx tsdevstack infra:remove-scheduler --job <job-name> --env <environment>

#Advanced Infrastructure Commands

These commands are typically called internally by higher-level commands but can be used directly for debugging or custom workflows.

#infra:generate-docker

Generate Dockerfiles for services.

npx tsdevstack infra:generate-docker --env <environment>

#infra:build-docker

Build Docker images with BuildKit.

npx tsdevstack infra:build-docker [service-name] --env <environment>

#infra:push-docker

Push Docker images to container registry.

npx tsdevstack infra:push-docker [service-name] --env <environment>

#infra:generate-kong

Generate Kong configuration for cloud deployment (infrastructure/kong/{env}/kong.yml, with secret placeholders; commit it).

npx tsdevstack infra:generate-kong --env <environment>

#infra:build-kong

Build and push the Kong Docker image for an environment: the same image definition as locally, with the framework plugins, your kong-plugins/ and the resolved config baked in. Deploy it with infra:deploy-kong.

npx tsdevstack infra:build-kong --env <environment>

#infra:remove-detached-worker

Remove orphaned detached workers from cloud.

npx tsdevstack infra:remove-detached-worker --worker <worker-name> --env <environment>

#Development npm Scripts

These npm scripts are available in your project root:

npm run dev          # Start all services with hot reload
npm run build        # Build all services
npm run test         # Run tests
npm run lint         # Run linting
npm run tsc          # Run TypeScript type checking

To stop services, press Ctrl+C in the terminal running npm run dev, or use docker compose down to stop containers.