For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/reference/cli-commands.md.

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:

TypeDescription
nestjsNestJS backend API
nextjsNext.js frontend
spaSingle-page application (Rsbuild)

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. To remove it from the cloud too, run infra:remove-service, then infra:deploy, in each environment it ran in.

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>

It adds the worker to config.json and creates whichever of the base service's src/worker.ts, src/worker.module.ts and tsconfig.worker.json are missing, plus the start-worker and start-worker:dev scripts. It never overwrites a file or a script, and lists what it created and what it left alone.

unregister-detached-worker

Remove a detached worker registration.

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

It only changes config.json. The worker's files and scripts stay; delete them yourself if you no longer need them.

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 RustFS (the first bucket adds the rustfs and rustfs-init services)
  • Regenerates secrets with STORAGE_ENDPOINT, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY, STORAGE_BUCKET_{NAME}

Options:

OptionDescription
--name <name>Bucket logical name (kebab-case, 2-30 chars). Prompted if omitted.

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 RustFS. Console at http://localhost:9001 (rustfsadmin/rustfsadmin).

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 RustFS data or cloud resources.

Options:

OptionDescription
--name <name>Bucket name to remove. Prompted if omitted.
--forceSkip confirmation prompt.

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:

OptionDescription
--name <name>Topic name (kebab-case). Prompted if omitted.
--publishers <services>Comma-separated publishing services. Prompted if omitted.
--subscribers <services>Comma-separated subscribing services. Prompted if omitted.

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:

OptionDescription
--name <name>Topic name to remove. Prompted if omitted.

update-messaging-topic

Update publishers and subscribers for an existing topic.

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

Options:

OptionDescription
--name <name>Existing topic name. Prompted if omitted.
--publishers <services>Comma-separated list (replaces current list entirely). Prompted if omitted.
--subscribers <services>Comma-separated list (replaces current list entirely). Prompted if omitted.
Warning

--publishers and --subscribers use replace semantics — always pass the complete desired list, not just additions.

Cloud Secrets Commands

cloud:init

Initialize cloud secrets provider integration.

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

cloud-secrets:push

Generate fresh framework secrets and push them, with your user secrets, to a cloud environment.

npx tsdevstack cloud-secrets:push --env <environment> [--skip-user-secrets]

--skip-user-secrets runs without prompts (CI, AI agents): it pushes the framework secrets and lists the user secrets still missing in the cloud.

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>

Without a value, it prompts, masked for credentials. In scripts, pipe the value in with --stdin. It stays out of the process list and your shell history:

printf '%s' "$STRIPE_KEY" | npx tsdevstack cloud-secrets:set STRIPE_KEY --stdin --env prod

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>

cloud-secrets:migrate

Copy secrets from where earlier versions kept them to where services read them now. The auth secrets move from shared to the auth service's scope. On Azure, each service's secrets move from the shared vault to its own. It never deletes or overwrites, so you can run it again. Run it before infra:deploy when you upgrade an existing environment.

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

cloud-secrets:cleanup

Delete the old copies after infra:deploy. Copies whose new copy has the same value are deleted after one question, which --force skips. A copy whose new copy has a different value is deleted only after a second question, never with --force. On Azure, it runs once every service is on the new deploy.

npx tsdevstack cloud-secrets:cleanup --env <environment> [--force]

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.

On GCP it reads the environment's Terraform state from the state bucket first, so an environment keeps the names it was deployed with (names). The credentials need read access to that bucket, as for every other infra command.

infra:plan

Show planned infrastructure changes.

npx tsdevstack infra:plan --env <environment>

A new CLI version can pin newer Terraform providers than the ones in an environment's lock file (.terraform.lock.hcl). Every command that runs Terraform then stops and asks for this step:

npx tsdevstack infra:plan --env <environment> --upgrade

It upgrades the providers and shows the plan. Nothing is applied. If the plan looks right, commit the updated lock file and run infra:deploy. CI uses the committed lock file.

infra:deploy

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

npx tsdevstack infra:deploy --env <environment>

If the provider has no capacity for a size you asked for (a database or Redis size in your region), the deploy waits 5 minutes and tries again, up to 3 times. This is a shortage on the provider's side, not a quota or configuration error. If it still fails, run the command again later; it continues where it stopped. Or pick another database.tier or redis.tier in infrastructure.json.

Images are tagged with the current commit, so commit before you deploy a change. Then the tag tells you which code runs. Every deploy starts new instances of each service, even with the same tag, so they read the current secrets. With uncommitted changes outside infrastructure/ and .tsdevstack/, the deploy warns you. --tag <tag> uses a tag of your choice instead. The other build and deploy commands take it too.

At the end, it prints the link to the environment's dashboard in the cloud's console. See Traces and Dashboards.

infra:destroy

Destroy infrastructure.

npx tsdevstack infra:destroy --env <environment>

On GCP, Google frees the network of the deleted services and database only after a while (up to 2 hours). If destroy stops with "Google has not released the network yet", run it again later. It removes what is left, and nothing left behind is billed.

On Azure, the DNS zone is deleted with the environment, with every record in it. Before it asks to go ahead, destroy lists the records the framework didn't make (Resend's email records, for example) and the command that saves a copy of the zone. A later deploy creates a new zone, maybe on other name servers, so check them at your registrar.

infra:deploy-service

Build, push, and deploy a single service.

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

For an SPA, files from earlier builds stay in the bucket for a day after their last upload. A visitor who still has the old version open can keep loading its pages. A later deploy deletes them.

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 one environment in the cloud: its containers, workers, database, migration job, SPA bucket, secrets and logs. On AWS it also deletes the service's own CloudFront distribution (SPA or Next.js), which CloudFront takes several minutes to disable before it can be deleted.

If the service subscribes to messaging topics, remove its subscriptions, deploy it and let it run for 15 minutes first: it then deletes its consumer groups in Redis. A group left behind stops the deleting of read messages on its topic. See How long messages stay in Redis.

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

Then take the service out of the project with remove-service, and run infra:deploy for the environment. The deploy removes the service's Kong routes, its load balancer routes and the scheduled jobs that call it. Until then, its routes and its domain stop working, and those jobs fail. The deploy also gives the other services the removed service's share of database connections: pool sizes are worked out at deploy (see Pool sizing), so until then they keep their smaller pools.

Before it drops the database, the command saves it to the environment's bucket of saved databases, where the file stays 7 days. infra:restore-database brings it back. If the save fails twice, a terminal asks whether to stop (the default), try again or remove the service without saving. CI and --confirm stop. See Data of a removed service.

Options:

OptionDescription
--env <environment>Target environment
--confirmSkip the prompts (required in CI)
--dry-runShow what would be deleted, delete nothing
--skip-exportDrop the database without saving it first

infra:restore-database

Replace a service's database with a file infra:remove-service saved. Run it once the service is deployed again: cloud-secrets:push, then infra:deploy.

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

Without a service name, a terminal lists the services that have saved files. CI needs the name.

It saves the database's current contents first, so a restore can be undone by restoring that file. By default it takes the newest file from a removal. In a terminal it lists the service's files to pick from. The service gets database errors while it runs. If the service's migrations are newer than the file, run infra:run-db-migrate afterwards.

Options:

OptionDescription
--env <environment>Target environment
--file <name>The saved file, for example auth-service/2026-11-14T12-30-00Z-removed.dump
--confirmSkip the confirmation (required in CI)

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:

OptionDescription
--githubUse GitHub Actions (auto-selected if omitted)
--envs <envs>Environments, comma-separated (prompted if omitted)
Auto-detected

NPM_TOKEN If your project root has an .npmrc, generated workflows automatically include a job-level env: NPM_TOKEN: ${{ secrets.NPM_TOKEN }} block (single global secret, not per-env) so private npm packages can be installed in CI. See CI/CD Setup — Private npm packages.

infra:generate-ci

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

npx tsdevstack infra:generate-ci
Auto-detected

NPM_TOKEN Like init-ci, this re-emits the NPM_TOKEN env block into every workflow if .npmrc exists at the project root. Re-run after creating an .npmrc to wire private-registry auth through the workflows.

infra:status

Check that infrastructure.json is valid for your cloud provider, and list the environments it overrides.

npx tsdevstack infra:status

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>

infra:logs

Read the logs of a deployed environment: services, workers, frontends, Kong, migration runs, scheduled jobs and the edge (load balancer and WAF). Without a source, it lists the sources and when each one last logged.

npx tsdevstack infra:logs --env <environment>
npx tsdevstack infra:logs [source] --env <environment>
npx tsdevstack infra:logs --all --env <environment> --since 2h --level error
npx tsdevstack infra:logs [source] --env <environment> --follow

Options:

OptionDescription
--allRead every source in one timeline
--since <time>Start of the window: 30m, 1h (default), 2d or a UTC time
--until <time>End of the window (default: now)
--level <level>This level and above: debug, info, warn, error, fatal. Leaves out lines without a level
--kind <kind>Only app, platform or edge lines
--grep <text>Lines that contain this text, in any case
--jsonOne JSON object per line
--followPrint new lines as they are written, until Ctrl+C. Stops after 1 hour. Not with --since or --until
--no-time-limitWith --follow: keep going until Ctrl+C

It prints every line of the window, oldest first, in UTC. See Cloud Logs.

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:

ProviderScheduler Service
GCPCloud Scheduler
AWSEventBridge Scheduler
AzureContainer Apps Jobs

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>
Auto-detected private-registry auth

If .npmrc exists at the project root, generated Dockerfiles include .npmrc in the deps-stage COPY and emit a BuildKit env-source secret mount on npm ci (--mount=type=secret,id=npm_token,env=NPM_TOKEN). See CI/CD Setup — Private npm packages.

infra:build-docker

Build Docker images with BuildKit.

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

NPM_TOKEN If .npmrc exists at the project root, the docker build invocation appends --secret id=npm_token,env=NPM_TOKEN automatically. Make sure NPM_TOKEN is exported in your shell (export NPM_TOKEN=… or ~/.zshrc) before running.

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. It uses the same image definition as locally, with the framework plugins, your kong-plugins/ and the resolved config baked in. The Redis password, the trust token and the frontend token are not in it. The config refers to them, and Kong reads them from its environment when it starts. 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.