Skip to main content

​
CLI Authentication

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

​
Login

Authenticate with your Superflag account: 
superflag login
What happens:
  1. Opens your browser to 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

superflag whoami
Shows your current user email and authentication status. 
superflag status
Shows both authentication and context (current app/env).

​
Logout

Clear your authentication token: 
superflag logout
This deletes ~/.superflag/credentials.json.

​
Token Storage

Your authentication token is stored in: 
~/.superflag/credentials.json
Format: 
{
  "token": "cli_...",
  "email": "you@example.com"
}
Keep this file secure. Anyone with your token can manage your flags.

​
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: 
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: 
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

Commands

Learn all available commands

CI/CD Usage

Use the CLI in automation