<!-- zibby-template-version: 1 -->
# /zibby-login — authenticate the CLI to Zibby Cloud

You are helping the user log in (or switch accounts) on the Zibby CLI.

Canonical docs: **https://docs.zibby.app/cli/auth**

## What login does

`zibby login` opens a browser flow to https://zibby.dev that:

1. Authenticates the user via their normal account login (email/password, Google, GitHub, …).
2. Issues a CLI session token, scoped to the user's default workspace.
3. Writes the token to `~/.zibby/session.json` (mode `0600`). This is what all subsequent `zibby agent / app / project / memory` commands authenticate with.

Workspaces are switched via `zibby workspace use <slug>` (separate command).

## Steps

1. **Check whether login is already valid:**
   ```
   Bash(zibby status)
   ```
   (See `/zibby-status` for the full surface.) If `Authenticated as <email>` and a recent timestamp, login is fresh — skip.

2. **Decide: interactive browser flow or API key?**
   - **Browser flow** — default. Run `zibby login`, opens a browser, user clicks "Authorize", token lands on disk. Best for human users on a workstation with a browser.
   - **API key** (PAT) — non-interactive. Set `ZIBBY_API_KEY=zby_<key>` in the env (or `--api-key` flag per-command). Best for CI, headless servers, no-browser environments.

3. **Run interactive login:**
   ```
   Bash(zibby login)
   ```
   The CLI prints a URL + 6-digit code. The user opens the URL, signs in, the CLI's local listener picks up the token and writes it to disk. Usually takes ~10 seconds end to end.

4. **If browser-less**, walk the user through API key:
   - Direct them to https://zibby.dev/settings/api-keys
   - "Create a new API key with the scopes you need" — usually `workflows:rw projects:r apps:rw`
   - They copy `zby_xxx`
   - For interactive use: `export ZIBBY_API_KEY=zby_xxx` in their shell
   - For one-off: pass `--api-key zby_xxx` per command

5. **Verify:**
   ```
   Bash(zibby status)
   ```
   Should report email + workspace + token type (`session` or `api-key`).

## Switching accounts

```
Bash(zibby logout)                  # clears ~/.zibby/session.json
Bash(zibby login)                   # re-auth as the other account
```

There's no multi-account session; one login at a time. For workspace switching within an account, `zibby workspace use <slug>`.

## Common pitfalls

- **Headless server, no browser** → the browser flow assumes a local browser can reach the loopback listener. On a remote SSH session, the listener URL won't resolve. Use API key path instead.
- **Token expired** → session tokens last 30 days. Re-run `zibby login`. CI should use API keys to avoid this.
- **`ZIBBY_API_KEY` env shadows the session token.** If the user has both, the env wins. Surprise sometimes: `unset ZIBBY_API_KEY` to fall back to the session token.
- **Wrong workspace** — if the user has multiple workspaces, login lands them on whichever is `default`. Switch with `zibby workspace use <slug>`.

## Out of scope here

- Multi-factor → handled at https://zibby.dev/security, not from CLI.
- Org / role management → web UI only.
