---
name: setup-session
description: Set up Tela API authentication via the CLI (browser-issued data-token JWT for production/staging, Docker+JWT for localhost). Use when the user needs to configure their Tela session or fix authentication errors.
---

# Setup Session

Set up the Tela API session. The CLI supports three environments:

- **Production/Staging** — Device flow: the installer prints a code and opens `accounts.tela.com`, where the user approves it and picks a workspace. Access tokens last 15 minutes and are refreshed automatically; a session unused for 7 days requires re-running the installer.
- **Localhost** — Docker discovery + JWT signing (for internal development)

## Usage

Run the installer and select an environment:

```bash
bunx @meistrari/tela-skills
```

### CLI Flags (non-interactive)

```bash
# Production/Staging
bunx @meistrari/tela-skills --env production --yes

# Localhost (fully non-interactive)
bunx @meistrari/tela-skills --env localhost --repos-path /path/to/tela --workspace <slug-or-id> --yes
```

## Verification

After setup, verify the session works by listing projects:

```bash
bun --preload ~/.claude/skills/tela-studio/preload.ts -e "console.log(JSON.stringify(await tela.listProjects(), null, 2))"
```

## Session File Locations

| Environment | Session Path | Auth Method |
|---|---|---|
| Production | `~/.tela/session.production` | Device flow: JSON with access + refresh tokens, auto-refreshed |
| Staging | `~/.tela/session.staging` | Device flow: JSON with access + refresh tokens, auto-refreshed |
| Localhost | `~/.tela/session.local` | JWT (auto-regenerated when expired) |

Additional localhost files:
- `~/.tela/.env` — `TELA_API_URL` and `TELA_APP_URL` (auto-discovered Docker ports; falls back to `:3000` if `tela-app` not running)
- `~/.tela/tela-repo-path` — Path to tela monorepo (for RSA key discovery)
- `~/.tela/environment` — Current active environment name

All session files have `600` permissions (readable only by owner).

Supported CLI-created sessions contain workspace claims used for automatic workspace inference. If a legacy or manually managed credential does not contain those claims, pass `workspaceId` explicitly to workspace-aware operations.

## Localhost Setup Details

The localhost flow:
1. Discovers Docker containers (`auth-api`, `auth-postgres`, `tela-api`, `tela-app`) and their mapped ports
2. Reads `AUTH_API_SECRET` from `packages/api/.env` and auth settings from `.repositories/auth-api/.env` in the tela monorepo
3. Fetches available workspaces from the local auth-api
4. Generates a JWT token through the local auth-api JWKS signing flow (30-day expiry)
5. Saves the token to `~/.tela/session.local` and writes port config to `~/.tela/.env`

Expired localhost tokens are auto-regenerated transparently when the API is called.

## Troubleshooting

### Production/Staging
1. Check the session file exists: `cat ~/.tela/session.production` or `cat ~/.tela/session.staging`
2. **"session expired and could not be refreshed"** — the refresh token is gone (unused for 7 days or revoked); re-run the installer
3. Ensure the account has the required permissions in Tela and that the workspace is entitled to the Tela application in the auth-api admin

### Localhost
1. **"auth-api not running"** — Start Docker services in the tela monorepo (`make dev`)
2. **"auth-postgres not running"** — Make sure the local auth database container is up and exposes its host port
3. **"No tela repo path saved"** — Run `bunx @meistrari/tela-skills` and select Localhost
4. **"Connection: FAILED"** — Check `docker ps | grep tela-api` is running
5. **Token expired** — Tokens auto-regenerate; if that fails, re-run the localhost setup