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.
Local Development Commands
sync
Regenerate all framework-managed configuration files. This is the most frequently used command.
What it generates:
kong.tsdevstack.yml- Gateway routes from OpenAPI specsdocker-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.
Types:
Example:
remove-service
Remove a service from the local project.
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.
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.
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.
generate-client
Generate TypeScript API client from OpenAPI spec.
Creates a typed API client package in packages/ that frontends can import.
validate-service
Validate a service follows naming conventions and structure.
Worker Commands
register-detached-worker
Register a worker for separate container deployment.
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.
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.
What it does:
- Adds bucket to
storage.bucketsinconfig.json - Regenerates
docker-compose.ymlwith RustFS (the first bucket adds therustfsandrustfs-initservices) - Regenerates secrets with
STORAGE_ENDPOINT,STORAGE_ACCESS_KEY,STORAGE_SECRET_KEY,STORAGE_BUCKET_{NAME}
Options:
Example:
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.
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:
Messaging Commands
add-messaging-topic
Add an async messaging topic to the project.
What it does:
- Adds topic to
messaging.topicsinconfig.json - Validates name (kebab-case, no duplicates)
- Validates publisher/subscriber service names exist and are NestJS type
- Runs
sync
Options:
Example:
remove-messaging-topic
Remove a messaging topic from the project.
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.
Options:
--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.
cloud-secrets:push
Generate fresh framework secrets and push them, with your user secrets, to a cloud environment.
--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.
cloud-secrets:set
Set or update a secret in cloud.
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:
cloud-secrets:get
Get a secret value from cloud.
cloud-secrets:list
List all secrets in cloud environment.
cloud-secrets:remove
Remove a secret from cloud.
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.
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.
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).
infra:init
Initialize infrastructure (creates Terraform state bucket).
infra:generate
Generate Terraform files.
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.
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:
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.
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.
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.
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.
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.
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:
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.
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:
infra:deploy-kong
Deploy Kong Gateway to Cloud Run.
infra:deploy-lb
Deploy External HTTP(S) Load Balancer for Kong Gateway.
infra:init-ci
Initialize CI/CD (generates GitHub Actions workflows). No cloud credentials required.
Options:
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.
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.
infra:list-deployed
List all deployed services in an environment.
infra:service-status
Check cloud resource status for a specific service.
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.
Options:
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.
The --service flag is required. It specifies which service's database to check.
infra:run-db-migrate
Apply pending database migrations.
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.
infra:deploy-schedulers
Deploy all scheduled jobs.
infra:list-schedulers
List scheduled jobs and their deployment status.
infra:remove-scheduler
Remove a scheduled job.
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.
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.
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.
infra:generate-kong
Generate Kong configuration for cloud deployment (infrastructure/kong/{env}/kong.yml, with secret placeholders; commit it).
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.
infra:remove-detached-worker
Remove orphaned detached workers from cloud.
Development npm Scripts
These npm scripts are available in your project root:
To stop services, press Ctrl+C in the terminal running npm run dev, or use docker compose down to stop containers.