tawa CLI Reference

The tawa CLI is the primary interface for interacting with the Tawa platform. Use it to deploy services, manage config, inspect builds, and administer OAuth clients.

Deploy & Build

These commands control the deploy pipeline and let you inspect build and runtime state.

tawa deploy

Deploy your service to the target environment.

tawa deploy              # Deploy to sandbox (default)
tawa deploy --prod       # Deploy to production
tawa deploy --uat        # Deploy to UAT
tawa deploy --watch      # Deploy and stream build logs in real time
tawa deploy --prod --watch

The builder clones your repo at the latest pushed commit, builds a Docker image, provisions databases and OAuth, deploys via Helm, and registers routes in Koko. See the Deploy Pipeline guide for the full sequence.

tawa status

Show the current build status and pod health for your linked service.

tawa status

tawa builds

List recent builds with status, commit SHA, and timestamps.

tawa builds

tawa logs

Stream live logs from the running pod, or view logs for a specific build.

tawa logs                    # Live pod logs
tawa logs --build <id>       # Build logs for a specific build ID

tawa pods

Show pod status including restart count and uptime.

tawa pods

tawa restart

Restart running pods without triggering a new build. Useful when you want to pick up rotated secrets or clear a stuck process.

tawa restart

tawa rollback

Roll back to the previous successful deployment.

tawa rollback

tawa validate / tawa preflight

Run pre-deploy checks to catch issues before building. Validates:

• catalog-info.yaml syntax and required fields
• Framework annotation matches your project
• Health endpoint is defined
• Git remote is accessible and branch is pushed
• OAuth callback route — if spec.auth.mode: sso is set, a route handler must be registered at the literal path /api/auth/callback. The scanner uses static analysis, so Express sub-router patterns (app.use('/api/auth', router) + router.get('/callback', ...)) will fail this check even if the route works at runtime. See the OAuth SSO guide for the correct pattern.

tawa validate
tawa preflight    # alias

Run this before your first deploy and after significant changes to catalog-info.yaml.

tawa destroy

Permanently remove a deployment and its Kubernetes namespace. Use with caution — this cannot be undone.

tawa destroy --namespace <service>-prod --force

tawa events

View the full audit log of deploys, config changes, credential rotations, and other platform events.

tawa events

tawa troubleshoot

AI-powered diagnostics for common issues including pod crashes, build failures, and connectivity problems.

tawa troubleshoot

Config & Secrets

Manage environment variables and secrets for your service. All secrets are encrypted at rest and injected into pods on deploy.

tawa config set

Set one or more environment variables. Use --secret for sensitive values — they are encrypted and their values are never returned by the API.

tawa config set LOG_LEVEL=debug API_TIMEOUT=30000
tawa config set STRIPE_SECRET_KEY=sk_live_xxx --secret
tawa config set MONGODB_URI=mongodb://... NEXTAUTH_SECRET=abc --secret

Changes take effect on the next deploy.

tawa config list

List all config vars and secret key names for your service. Secret values are hidden.

tawa config list

tawa config unset

Remove a config var or secret.

tawa config unset KEY_NAME

tawa config pull

Pull all config vars and decrypted secrets to a local .env.local file for development. The file is written with restricted permissions.

tawa config pull

WARNING: Never commit .env.local to git. It is written to your working directory and should be in .gitignore.

Services

Manage service registrations in the platform registry.

tawa services list

List all services registered to your organization.

tawa services list

tawa services update

Update settings for a registered service.

tawa services update <service-id> --name new-name
tawa services update <service-id> --branch develop
tawa services update <service-id> --helm-chart helm/          # Set custom Helm chart path
tawa services update <service-id> --helm-chart ""             # Clear custom chart (use platform default)

tawa services delete

Delete a service registration. Does not remove the deployed pod — use tawa destroy for that.

tawa services delete <service-id>

OAuth

Manage Bio-ID OAuth clients provisioned for your services.

tawa oauth list

List all OAuth clients for your organization.

tawa oauth list

tawa oauth get

Inspect a specific OAuth client — redirect URIs, scopes, grant types.

tawa oauth get <client-id>

tawa oauth add-uri

Add a redirect URI to an OAuth client. Useful for adding a local development redirect.

tawa oauth add-uri <client-id> http://localhost:3000/api/auth/callback

tawa oauth remove-uri

Remove a redirect URI from an OAuth client.

tawa oauth remove-uri <client-id> <uri>

tawa oauth regenerate-secret

Rotate the OAuth client secret. Invalidates the existing secret immediately — update BIO_CLIENT_SECRET via tawa config set --secret and redeploy.

tawa oauth regenerate-secret <client-id>

tawa oauth delete

Delete an OAuth client. Use with caution — any service using this client will stop being able to authenticate users.

tawa oauth delete <client-id>

Wallet & Gas

Manage your organization's gas token wallet.

tawa wallet

Show your current gas token balance and recent spending summary.

tawa wallet

tawa wallet buy

Purchase additional gas tokens. Amount is in tokens (1 token = $0.01 USD).

tawa wallet buy 10000    # Buy 10,000 tokens ($100)

tawa gas

View gas spending breakdown by service and operation type.

tawa gas

Domains

Manage custom domains for your services.

tawa domain add

Add a custom domain to your service. The platform creates a DNS record automatically if --cloudflare is provided and your domain is managed through the platform's Cloudflare account.

tawa domain add docs.example.com
tawa domain add docs.example.com --cloudflare

tawa domain list

List all custom domains configured for your services.

tawa domain list

tawa domain remove

Remove a custom domain from your service.

tawa domain remove docs.example.com

Project Setup

Commands for initializing and linking services.

tawa init

Scaffold a new service project with catalog-info.yaml, health endpoint, and basic project structure.

tawa init my-service

tawa link

Link the current directory to an existing service registration. Writes .tawa.yaml with the service ID, repo URL, and branch.

tawa link

Run this in a project directory after cloning a repo that was already registered with the platform.

tawa local-setup

One command to configure a service for local development. Registers the localhost redirect URI in Bio-ID, regenerates the OAuth client secret, pulls all sandbox config vars, and writes .env.local with BIO_CLIENT_ID, BIO_CLIENT_SECRET, and APP_URL set to localhost.

tawa local-setup                        # port 3000, writes .env.local
tawa local-setup --port 3847            # custom dev server port
tawa local-setup --skip-config          # only write Bio-ID creds, skip config pull
tawa local-setup --output .env.test     # write to a different file

The service must already be deployed to sandbox before running this — the builder creates the sandbox OAuth client on first deploy.

WARNING: Never commit .env.local to git. It contains decrypted secrets.

tawa sample

Scaffold a sample service from a template.

tawa sample --api my-service      # Express API template
tawa sample --next my-site        # Next.js app template