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

# Authentication

> Authenticate the Superflag CLI with your account

# CLI Authentication

The Superflag CLI uses browser-based authentication with a localhost callback flow.

## Login

Authenticate with your Superflag account:

```bash theme={null}
superflag login
```

**What happens:**

1. Opens your browser to [https://superflag.sh/cli/login](https://superflag.sh/cli/login)
2. You log in with your Superflag account
3. Browser redirects to `http://localhost:3737/callback` with your token
4. CLI receives the token and stores it in `~/.superflag/credentials.json`
5. You're authenticated!

## Check Authentication Status

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

Shows your current user email and authentication status.

```bash theme={null}
superflag status
```

Shows both authentication and context (current app/env).

## Logout

Clear your authentication token:

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

This deletes `~/.superflag/credentials.json`.

## Token Storage

Your authentication token is stored in:

```
~/.superflag/credentials.json
```

**Format:**

```json theme={null}
{
  "token": "cli_...",
  "email": "you@example.com"
}
```

<Warning>
  Keep this file secure. Anyone with your token can manage your flags.
</Warning>

## Troubleshooting

### Port 3737 Already in Use

If port 3737 is already in use, the login flow will fail. Stop any process using port 3737 and try again:

```bash theme={null}
lsof -ti:3737 | xargs kill -9
superflag login
```

### Browser Doesn't Open

If the browser doesn't open automatically:

1. Copy the URL shown in the terminal
2. Open it manually in your browser
3. Complete the login flow

### Token Expired

If you get "Not authenticated" errors, log in again:

```bash theme={null}
superflag login
```

## Security

* Tokens are scoped to your user account
* Tokens do not expire automatically
* You can revoke access by logging out and deleting credentials
* Tokens are stored locally and never transmitted except to Superflag APIs

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands" icon="terminal" href="/cli/commands">
    Learn all available commands
  </Card>

  <Card title="CI/CD Usage" icon="robot" href="/cli/ci-cd">
    Use the CLI in automation
  </Card>
</CardGroup>