Local Dev Setup

About

Covers `tawa local-setup` — the single command that replaces the multi-step manual process of registering a localhost redirect URI, regenerating a client secret, and pulling sandbox config vars. Explains what gets written to .env.local, the APP_URL override, prerequisites, and common mistakes developers hit when running services locally.

Skill Content

This is the raw markdown that gets installed as a Claude Code command.

# Local Development Setup

## What this skill covers
How to get a Tawa service running locally with Bio-ID OAuth configured — one command replaces a multi-step manual process.

## The Command

```bash
tawa local-setup
```

Run this once from your project directory after cloning. It replaces the full manual setup flow.

## What It Does (5 Steps)

1. **Finds the sandbox OAuth client** — looks up `{service}-sandbox` in Bio-ID
2. **Registers the localhost redirect URI** — adds `http://localhost:{port}/api/auth/callback` if not already present
3. **Regenerates the client secret** — produces a fresh `BIO_CLIENT_SECRET` for local use
4. **Pulls all sandbox config vars** — downloads every config var and decrypted secret from the builder
5. **Writes `.env.local`** — merges everything with `BIO_CLIENT_ID`, `BIO_CLIENT_SECRET`, and `APP_URL` overridden to localhost

## Options

```bash
tawa local-setup                        # port 3000, writes .env.local in cwd
tawa local-setup --port 3847            # custom dev server port
tawa local-setup --service my-service   # explicit service name
tawa local-setup --skip-config          # only write Bio-ID creds, skip config pull
tawa local-setup --output .env.test     # write to a different file
```

## Prerequisites

- Service must already be deployed to sandbox (`tawa deploy`)
- You must be logged in (`tawa login`)
- Run from a directory containing `.tawa.yaml` or `catalog-info.yaml`

## What Gets Written to .env.local

```bash
# All sandbox config vars (same as tawa config pull)
MONGODB_URI=mongodb://...
REDIS_URL=redis://...
SOME_API_KEY=...

# Bio-ID OAuth credentials for the sandbox client
BIO_CLIENT_ID=my-service-sandbox
BIO_CLIENT_SECRET=secret_...

# APP_URL overridden to localhost (not the sandbox URL)
APP_URL=http://localhost:3000
```

The `APP_URL` override is critical — without it, your service would build OAuth redirect URIs pointing to the sandbox domain instead of localhost, and the flow would fail.

## After Running

Restart your dev server to pick up the new credentials:

```bash
npm run dev
# or
tawa local-setup --port 3847 && npm run dev -- -p 3847
```

## Important Notes

- `.env.local` is merged, not replaced — existing values you set manually are preserved unless overridden by a pulled var
- Run again any time you add new config vars to sandbox (`tawa config set`) to sync them locally
- Never commit `.env.local` to git — it contains decrypted secrets
- The client secret is regenerated each time you run `local-setup` — this invalidates the previous secret, which is fine for local dev

## Common Mistakes

- Running without deploying to sandbox first — the OAuth client (`{service}-sandbox`) is created by the builder on first deploy
- Using a different port in `npm run dev` than in `--port` — the redirect URI registered in Bio-ID must match exactly
- Hardcoding `BIO_CLIENT_ID` or `BIO_CLIENT_SECRET` in code — always read from `process.env`
- Committing `.env.local` — add it to `.gitignore`

Install

Copy the skill content and save it to:

~/.claude/commands/local-setup.md

Details

Format

Command

Category

configure

Version

1.0.0

Tokens

~700

Updated

2026-03-01