Tawa CLI

Developer CLI for the Tawa platform - Deploy, manage, and monitor cloud services with a single command.

Tawa is a modern cloud platform CLI that handles the complete deployment lifecycle - from scaffolding to production. Built for developers who want to ship fast without DevOps overhead.

✨ Features

• 🚀 Zero-Config Deployments - Auto-generates Dockerfiles, provisions databases, configures DNS
• 🔐 Built-in OAuth - Automatic SSO integration with Bio-ID
• 💾 Database Provisioning - MongoDB, Redis, Neo4j auto-configured per environment
• 🔑 Secrets Management - Encrypted secrets with AES-256-GCM
• 🌐 Custom Domains - Bring your own domain with auto-SSL
• 🤖 AI-Powered Setup - Interactive project scaffolding with Claude
• 📊 Real-time Monitoring - Stream logs, check health, troubleshoot deployments
• 🔄 Credential Rotation - Automatic database credential rotation with Vault
• 💰 Gas Wallet - Token-based resource billing and management

📦 Installation

npm install -g tawa

Or use without installing:

npx tawa deploy

🚀 Quick Start

1. Create an account

tawa signup

This creates:

• Your developer account
• An organization (team workspace)
• A gas wallet with 50,000 free intro tokens

2. Scaffold a project

# Static site (HTML/CSS/JS)
tawa sample --static my-site

# Next.js app
tawa sample --nextjs my-app

# Express/Hono API
tawa sample --api my-api

# AI-powered setup (for existing projects)
tawa init --ai

3. Deploy

cd my-site
tawa deploy --watch

Your app is now live at https://my-site.sandbox.tawa.insureco.io!

📚 Command Reference

Authentication & Identity

| Command | Description | |---------|-------------| | tawa signup | Create account, org, and wallet | | tawa login | Authenticate with Bio-ID and Forgejo | | tawa login --skip-git | Skip Forgejo authentication | | tawa login --save | Save credentials for auto-re-login | | tawa logout | Sign out (clears all tokens) | | tawa whoami | Show current user and org | | tawa tokens | Display authentication tokens and expiry | | tawa tokens --reveal | Show full token values | | tawa refresh | Refresh auth token without re-entering credentials |

Project Setup

| Command | Description | |---------|-------------| | tawa init | Scaffold catalog-info.yaml for existing project | | tawa init --ai | AI-powered interactive setup | | tawa sample --static <name> | Create static HTML/CSS/JS site | | tawa sample --nextjs <name> | Create Next.js starter | | tawa sample --api <name> | Create Express/Hono API | | tawa sample --crosspod | Create pod-to-pod auth demo | | tawa preflight | Run pre-deployment checks | | tawa validate | Validate catalog-info.yaml |

Deployment & Build

| Command | Description | |---------|-------------| | tawa deploy | Build and deploy to sandbox (default) | | tawa deploy --prod | Deploy to production | | tawa deploy --uat | Deploy to UAT | | tawa deploy --watch | Watch build progress in real-time | | tawa link | Connect repo to builder (legacy) | | tawa unlink | Disconnect repo from builder | | tawa builds | List recent builds | | tawa status | Show service and build status | | tawa destroy | Delete deployment and K8s resources | | tawa destroy --namespace <ns> --force | Force destroy |

Monitoring & Debugging

| Command | Description | |---------|-------------| | tawa logs | Stream container logs | | tawa logs --build <id> | View build logs | | tawa logs -f | Follow logs (live tail) | | tawa pods | Show pod status and health | | tawa troubleshoot | AI-powered diagnostics | | tawa troubleshoot --auto-fix | Apply suggested fixes |

Service Management

| Command | Description | |---------|-------------| | tawa services list | List all registered services | | tawa services list --json | Output as JSON | | tawa services update <id> --name <name> | Rename service | | tawa services update <id> --branch <branch> | Change deployment branch | | tawa services update <id> --helm-chart <path> | Set custom Helm chart | | tawa services update <id> --helm-chart "" | Clear custom chart | | tawa services delete <id> | Delete service registration |

Config & Secrets

| Command | Description | |---------|-------------| | tawa config list | List config vars and secret names | | tawa config set KEY=VALUE | Set plain config var | | tawa config set KEY=VALUE --secret | Set encrypted secret | | tawa config set KEY1=VAL1 KEY2=VAL2 | Set multiple vars | | tawa config unset KEY | Remove config var or secret | | tawa config pull | Pull config + secrets to .env.local | | tawa config push | Push .env.local to platform |

Database Management

| Command | Description | |---------|-------------| | tawa db connect <service> | Get MongoDB connection string | | tawa db connect <service> --prod | Production environment | | tawa db connect <service> --ttl 12 | Custom TTL (1-24 hours) | | tawa db whitelist <service> | List active IP whitelist entries | | tawa db revoke <service> <id> | Revoke database access |

Custom Domains

| Command | Description | |---------|-------------| | tawa domain add <domain> | Add custom domain | | tawa domain add <domain> --prod | Add to production | | tawa domain list | List all custom domains | | tawa domain verify <domain> | Verify DNS records | | tawa domain status <domain> | Check domain status | | tawa domain remove <domain> | Remove custom domain |

Git & Forgejo

| Command | Description | |---------|-------------| | tawa git login | Show Forgejo login instructions | | tawa git login <token> | Login with PAT | | tawa git logout | Logout from Forgejo | | tawa git create <repo> | Create repository with auto-deploy | | tawa git create <repo> --webhook | Add webhook | | tawa git list | List repositories | | tawa git get <repo> | Get repository details | | tawa git clone <repo> | Clone repository | | tawa git delete <repo> --yes | Delete repository | | tawa git ssh-key | Add SSH key to Forgejo | | tawa git ssh-keys | List SSH keys | | tawa git webhook <repo> | Add auto-deploy webhook |

OAuth & Scopes

| Command | Description | |---------|-------------| | tawa oauth list | List OAuth clients | | tawa oauth get <client-id> | Get client details | | tawa oauth create <name> | Create OAuth client | | tawa oauth add-uri <client-id> <uri> | Add redirect URI | | tawa oauth remove-uri <client-id> <uri> | Remove redirect URI | | tawa oauth regenerate-secret <client-id> | Regenerate client secret | | tawa oauth delete <client-id> | Delete OAuth client | | tawa scopes list | List available scopes | | tawa scopes request <service> <scope> | Request scope grant | | tawa scopes grant <request-id> | Approve scope request | | tawa scopes deny <request-id> | Deny scope request | | tawa scopes revoke <grant-id> | Revoke granted scope |

Organization Management

| Command | Description | |---------|-------------| | tawa org invite <email> | Invite user to organization | | tawa org join <code> | Join organization with invite code | | tawa org invites | List pending invitations | | tawa org revoke <invite-id> | Revoke invitation | | tawa org members | List organization members |

User Management (Admin)

| Command | Description | |---------|-------------| | tawa user create | Create new user (admin only) | | tawa user set-password <user-id> | Reset user password | | tawa user search <query> | Search users |

Other Commands

| Command | Description | |---------|-------------| | tawa update | Check for CLI updates | | tawa settings | View/edit CLI settings |

📝 Configuration Files

catalog-info.yaml (Project Config)

Defines your service configuration:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-api
  description: My awesome API
  annotations:
    insureco.io/framework: nextjs      # nextjs, express, hono, static
    insureco.io/node-version: "20"
    insureco.io/pod-tier: nano         # nano, small, medium, large, xlarge
    insureco.io/health-endpoint: /api/health
spec:
  type: service
  lifecycle: production
  owner: my-org                        # Auto-set by tawa sample

  # API routes (registered in Koko gateway)
  routes:
    - path: /api/users
      methods: [GET, POST]
      auth: required

  # Auto-provision databases
  databases:
    - type: mongodb    # Creates MONGODB_URI env var
    - type: redis      # Creates REDIS_URL env var
    - type: neo4j      # Creates NEO4J_URI env var

  # Internal service dependencies
  dependencies:
    - service: iec-wallet
      port: 3000       # Creates IEC_WALLET_URL env var

~/.tawa/config.yaml (Global Config)

koko_url: https://koko.tawa.insureco.io
builder_url: https://builder.tawa.insureco.io
bio_url: https://bio.tawa.insureco.io

~/.tawa/auth.yaml (Auth Tokens)

Managed automatically by tawa login. Use tawa tokens to view.

🌍 Environments

| Flag | Namespace | URL Pattern | |------|-----------|-------------| | (default) | {service}-sandbox | {service}.sandbox.tawa.insureco.io | | --prod | {service}-prod | {service}.tawa.insureco.io | | --uat | {service}-uat | {service}.uat.tawa.insureco.io |

💰 Gas & Wallets

Tawa uses a token-based billing system:

• 1 gas token = $0.01 USD
• New accounts get 50,000 free intro tokens
• Tokens pay for hosting (pod uptime) and transactions (API calls)

Pod Pricing

| Tier | CPU | Memory | Gas/Hour | USD/Month | |------|-----|--------|----------|-----------| | nano | 0.25 | 256Mi | 5 | $36 | | small | 0.5 | 512Mi | 10 | $72 | | medium | 1 | 1Gi | 23 | $165.60 | | large | 2 | 2Gi | 42 | $302.40 | | xlarge | 4 | 4Gi | 83 | $597.60 |

Wallet Commands

tawa wallet              # Check balance
tawa wallet buy 10000    # Purchase tokens
tawa gas                 # View gas spending

🔐 Secrets Management

All secrets are encrypted at rest with AES-256-GCM:

# Set encrypted secrets
tawa config set MONGODB_URI=mongodb://... --secret
tawa config set NEXTAUTH_SECRET=abc123 --secret

# Set plain config (not encrypted)
tawa config set LOG_LEVEL=debug

# Pull all config + decrypted secrets to .env.local
tawa config pull

Secrets are decrypted during deployment and injected as Kubernetes Secrets.

🤖 AI-Powered Setup

Use Claude to scaffold projects interactively:

cd my-existing-project
tawa init --ai

The AI will:

• Analyze your codebase
• Ask clarifying questions
• Generate catalog-info.yaml
• Configure databases, routes, and dependencies

🔄 Automatic Features

When you run tawa deploy, the platform automatically:

1. ✅ Generates optimized Dockerfile (if not present)
2. ✅ Provisions databases (MongoDB, Redis, Neo4j)
3. ✅ Creates OAuth client for SSO
4. ✅ Configures DNS records
5. ✅ Injects environment variables
6. ✅ Registers service in Koko gateway
7. ✅ Sets up health checks
8. ✅ Configures ingress and SSL

📊 Monitoring Example

# Check service status
tawa status

# Stream logs
tawa logs -f

# View pod health
tawa pods

# AI-powered troubleshooting
tawa troubleshoot --auto-fix

🛠️ Development

# Clone the repo
git clone https://github.com/insurecosys/iec-cli.git
cd iec-cli

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Build
npm run build

# Test
npm test

📦 Publishing

npm version patch     # or minor, major
npm publish           # runs prepublishOnly (build) automatically
git push              # push version bump to remote

🆘 Troubleshooting

"Token is not active"

Your Bio-ID token expired. Run tawa login to refresh.

"Deploy gate: insufficient gas reserve"

Top up your wallet:

tawa wallet buy 10000

"Repository not found"

Make sure your repo is accessible:

tawa git list              # Check if repo exists
tawa git ssh-key           # Add SSH key if needed

Build failing?

Run preflight checks:

tawa preflight

Or use AI troubleshooting:

tawa troubleshoot --auto-fix

📖 Documentation

• Full Documentation
• CLI Reference
• Platform Architecture
• API Reference

🤝 Contributing

Contributions welcome! Please read our Contributing Guide first.

📄 License

MIT © InsurEco

🔗 Links

• Homepage
• Documentation
• GitHub Issues
• NPM Package

Built with ❤️ by the InsurEco team