> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora auth

> Sign in, switch workspaces, manage tokens.

The `auth` subcommand manages your local credentials and which workspace subsequent commands act on. Sign-in is OAuth-based; the CLI stores a token per user under your OS's config directory.

## Commands

| Command                       | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `auth login`                  | Open browser for OAuth sign-in.                  |
| `auth logout`                 | Delete local credentials.                        |
| `auth status`                 | Print active workspace + token summary.          |
| `auth workspaces list`        | List all workspaces you belong to.               |
| `auth workspaces switch <id>` | Change the active workspace.                     |
| `auth workspaces current`     | Print the active workspace id (script-friendly). |

## `auth login`

```bash theme={null}
nora auth login
```

Opens a browser window for OAuth. On success:

* Fetches your list of workspaces.
* Pins the first one as active if you didn't already have one.
* Writes credentials to your OS config location:
  * macOS: `~/Library/Application Support/nora/credentials.json`
  * Linux: `~/.config/nora/credentials.json`
  * Windows: `%APPDATA%\nora\credentials.json`

The credentials file is chmod 0600 (read-only for you). Never commit it or share it.

If your terminal has no browser (SSH, container), the CLI prints a URL to paste into a browser locally. Copy the returned code back into the terminal.

## `auth logout`

```bash theme={null}
nora auth logout
```

Deletes the local credentials file. **Does not revoke the token server-side.** To revoke, use the app: **Settings → Personal Access Tokens → Revoke**.

Useful after signing in on a shared machine.

## `auth status`

```bash theme={null}
nora auth status
```

Prints:

* Active workspace name and id.
* All saved workspaces (name + id + role).
* Token (redacted, showing prefix only).
* Server URL you're pointed at.

Good first command when something doesn't feel right — confirms *which* workspace is active and *which* server the CLI talks to.

## `auth workspaces list`

```bash theme={null}
nora auth workspaces list
```

Refreshes the workspace list from the server (falls back to cache when offline). Each entry shows role (`owner` / `manager` / `member`) so you know your permissions before running destructive commands.

## `auth workspaces switch <id>`

```bash theme={null}
nora auth workspaces switch acme-prod
```

Sets the active workspace. All subsequent commands act on it until you switch again.

You can also override per-command without switching:

```bash theme={null}
nora --workspace acme-staging flows list
```

## `auth workspaces current`

```bash theme={null}
nora auth workspaces current
```

Prints just the active workspace id. Handy in shell scripts:

```bash theme={null}
WS=$(nora auth workspaces current)
echo "Deploying to $WS"
```

## Multiple accounts on one machine

The CLI stores one active credential set. To use different accounts:

```bash theme={null}
NORA_TOKEN=$OTHER_ACCOUNT_TOKEN nora flows list
```

Or maintain multiple credential files by pointing `NORA_CONFIG_DIR`:

```bash theme={null}
NORA_CONFIG_DIR=~/.nora-dev nora auth login    # sign in as one identity
NORA_CONFIG_DIR=~/.nora-prod nora auth login   # separately sign in as another
```

Then alias each for quick switching:

```bash theme={null}
alias nora-dev='NORA_CONFIG_DIR=~/.nora-dev nora'
alias nora-prod='NORA_CONFIG_DIR=~/.nora-prod nora'
```

## Personal vs. workspace tokens

Two token types both work:

| Token type                | Where it comes from                  | Scope                       | Best for          |
| ------------------------- | ------------------------------------ | --------------------------- | ----------------- |
| **Personal access token** | `auth login` or app UI               | Any workspace you belong to | Interactive use   |
| **Workspace token**       | App: **Settings → Workspace Tokens** | Pinned to one workspace     | CI/CD, automation |

Workspace tokens are the right choice for CI: they can't accidentally act on the wrong workspace, and revoking one doesn't sign your user out of the app.

For CI, set `NORA_TOKEN` as a secret:

```yaml theme={null}
env:
  NORA_TOKEN: ${{ secrets.NORA_CI_TOKEN }}
```

No `auth login` needed — the CLI picks up `NORA_TOKEN` automatically.

## Token lifetime

* **Personal access tokens**: valid until you revoke. Auto-refresh on use.
* **Workspace tokens**: valid until you revoke or the workspace deletes them.

The CLI's status output shows the token's issue time so you can rotate stale tokens.

## Troubleshooting

**"Not authenticated"** — run `auth login`, or set `NORA_TOKEN`.

**"Wrong workspace"** — `auth status` to confirm active workspace, then `auth workspaces switch` to fix.

**"401 from server despite valid token"** — the token was revoked in the UI. Re-`auth login`.

**Corporate proxy blocks OAuth** — set `HTTPS_PROXY=http://your-proxy:port` before `auth login`.