> ## Documentation Index
> Fetch the complete documentation index at: https://developers.nexspace365.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Authentication

> Authenticate the NexSpace CLI with API keys or OAuth

# CLI Authentication

The CLI authenticates with either a browser OAuth session (device-code flow) or
a stored API key / PAT. Either way, `nexspace login` saves the credential to
your **OS keychain** when available (macOS Keychain, Linux Secret Service,
Windows Credential Manager), falling back to `~/.nexspace/config.json`
(mode `0600`).

## Device Code Login (Interactive)

Best for personal use on your workstation:

```bash theme={null}
nexspace login          # browser OAuth (device-code) by default
nexspace login-device   # explicit alias for the same flow
```

This opens a browser where you log in and approve the CLI. The CLI refreshes the
OAuth access token automatically as it nears expiry.

## API Key / PAT (Headless)

Best for CI/CD, scripts, and automation. Store the key once with
`nexspace login --token` — it also reads the `NEXSPACE_API_KEY` environment
variable as a fallback for the token value:

```bash theme={null}
nexspace login --token nex_live_YOUR_KEY
# or
NEXSPACE_API_KEY=nex_live_YOUR_KEY nexspace login
```

Once stored, every command reuses the credential automatically:

```bash theme={null}
nexspace facilities list
```

## Verify Authentication

```bash theme={null}
nexspace whoami
```

Prints the identity the stored credential authenticates as, backed by
`GET /api/auth/me`.

## Logout

```bash theme={null}
nexspace logout
```

Removes stored credentials from the keychain and `~/.nexspace/config.json`.