---
name: railway-cli-local-auth
description: Loads Railway CLI authentication from this repo’s gitignored API env files before running railway commands. Use when railway whoami returns Unauthorized, when running railway link/variable/logs from a terminal, or when deploying or debugging any client via the CLI.
---

# Railway CLI — local auth (yeshuman monorepo)

## Problem

The **`railway` binary does not read** `api/.env`, `api/.env.lortsmith`, or other dotenv files. If **`RAILWAY_API_TOKEN`** is not exported in the current shell, **`railway whoami`** returns **Unauthorized** even when the token is valid and **account-scoped**.

## Fix: export token from the right file

From **`cd api`**:

1. Pick the env file that holds **`RAILWAY_API_TOKEN`** for the workspaces you use (often shared across clients).
2. **Source** it so variables export to the shell (never paste token values into chat or commit these files).

**Lort Smith (example):**

```bash
cd api
set -a && . ./.env.lortsmith && set +a
railway whoami
```

**Other clients:** `. ./.env`, `. ./.env.employment`, `. ./.env.health`, etc. — see [`api/env.example`](../../api/env.example). **Lumie local dev** often uses [`api/.env.health`](../../api/.env.health) for `CLIENT_CONFIG=lumie`; the **Railway token** may still live in [`api/.env`](../../api/.env) or the same file—whatever actually defines `RAILWAY_API_TOKEN`.

**Workspace:** if `railway link` asks for a workspace interactively, pass **`--workspace <name>`** (or `-w`) to match the Railway dashboard team/workspace when scripting.

**Verify:**

```bash
railway whoami
```

Expect a logged-in user email, not `Unauthorized`.

## Token type (must match CLI)

- **`RAILWAY_API_TOKEN`**: account API token from [railway.com/account/tokens](https://railway.com/account/tokens), **No workspace** scope, for `whoami`, `link`, `variable`, `logs`.
- **`RAILWAY_TOKEN`**: **project** deploy token (`railway up`); **not** a substitute for account CLI auth.

Details: [`.cursor/rules/railway.mdc`](../../.cursor/rules/railway.mdc), [`api/env.example`](../../api/env.example).

## Safe variable inspection

- **Do not** run **`railway variable list --json`** (or paste full `variable list` output) into agent chat or shared logs—it prints **secrets**.
- Prefer **Railway UI** → Variables, **`railway open`**, or ask a human to confirm specific keys. See **Agent / operator safety** in `railway.mdc`.

## After auth: link and commands

Link state lives under **`api/.railway/`** when you run the CLI from **`api/`**.

```bash
cd api
set -a && . ./.env.lortsmith && set +a
railway link --project <slug> --environment production --service lortsmith-api
railway variable list
railway logs
```

Use the real **project slug** from `railway list` or the dashboard (may differ from the code “client handle”). For **UI**, re-link with `--service <client>-ui` or `railway service <client>-ui`.

Longer Lort Smith checklist: [`docs/LORTSMITH_RAILWAY_RUNBOOK.md`](../../docs/LORTSMITH_RAILWAY_RUNBOOK.md).

## Agent / automation note

When running Railway CLI from an agent shell, **always** `cd` to **`api/`** (or the directory where `.railway` was created), **source** the file that contains **`RAILWAY_API_TOKEN`**, then run **`railway`**. Do not assume a prior step exported the token.

## Related

- PR / deploy triage: [railway-pr-deploy-triage](../railway-pr-deploy-triage/SKILL.md)
- Email variables: [railway-email-configuration](../railway-email-configuration/SKILL.md)