Nile CLI supports two primary methods of authentication:
  1. Browser-based OAuth authentication (Recommended)
  2. API key authentication

​
Browser-based Authentication

Browser-based authentication provides a secure and convenient way to connect to Nile. When you run the login command, the CLI will:
  1. Open your default browser
  2. Direct you to Nile’s authentication page
  3. After successful login, automatically configure your CLI
Browser Login
# Start the authentication flow
nile connect login

# Example output
Opening authorization URL: https://console.thenile.dev/authorize
Authentication successful!
✓ Successfully connected to Nile!

​
Authentication Flow

The following illustrate the browser-based authentication flow:
  1. CLI initiates auth flow
  2. Browser opens to Nile login
  3. User authenticates
  4. Token returned to CLI
  5. CLI stores credentials

​
Verifying Connection

After authentication, verify your connection:
Verify Connection
# Check connection status
nile connect status

# Example output
✓ Connected to Nile

# Try a simple command
nile workspace list

​
Session Management

Browser-based authentication creates a session that:
  • Remains valid for extended periods
  • Automatically refreshes when needed
  • Can be explicitly terminated
Session Management
# Check current session
nile connect status

# End your session
nile connect logout

# Start a new session
nile connect login

​
API Key Authentication

For automated workflows or CI/CD environments, you can use API key authentication. API keys can be:
  • Used directly in commands
  • Stored in configuration
  • Set via environment variables

​
Using API Keys

API Key Examples
# 1. Direct usage in commands
nile --api-key YOUR_API_KEY db list

# 2. Save in configuration
nile config --api-key YOUR_API_KEY

# 3. Use environment variable
export NILE_API_KEY=YOUR_API_KEY
nile db list

​
API Key Best Practices

API Key Security
# 1. Store in environment file
echo "NILE_API_KEY=your-api-key" >> .env
echo ".env" >> .gitignore

# 2. Use in CI/CD (GitHub Actions example)
env:
  NILE_API_KEY: ${{ secrets.NILE_API_KEY }}

# 3. Regular rotation
nile config --api-key NEW_API_KEY

​
Common Issues and Debugging

​
Authentication Failures

When authentication fails:
Auth Issues
# 1. Connection timeout
nile connect login
Error: Authentication timed out after 2 minutes

# Solution: Try again or check network

# 2. Invalid API key
nile --api-key INVALID_KEY db list
Error: Invalid API key

# Solution: Verify API key or try browser auth
nile connect login

​
Network Issues

When experiencing network problems:
Network Debug
# Enable debug output
nile --debug connect login

# Example output
Debug - Auth parameters:
Debug - Auth URL: https://console.thenile.dev/authorize
Debug - Starting auth with config:
Debug - Received callback request: /callback

​
Session Issues

When encountering session problems:
Session Issues
# 1. Check session status
nile connect status
Not connected to Nile

# 2. Clear existing session
nile connect logout

# 3. Remove stored credentials
rm ~/.nile/credentials

# 4. Start fresh session
nile connect login

​
Environment Configuration

Configure your environment for different authentication methods:
Environment Setup
# 1. Development (browser-based)
nile connect login
nile config --workspace dev

# 2. CI/CD (API key)
export NILE_API_KEY=your-api-key
export NILE_WORKSPACE=ci-cd

# 3. Production (API key)
export NILE_API_KEY=prod-api-key
export NILE_WORKSPACE=production

​
Workspace Selection

After authentication, select your workspace:
Workspace Selection
# List available workspaces
nile workspace list

# Set default workspace
nile config --workspace my-workspace

# Verify workspace
nile workspace show
  • nile connect status - Check connection status
  • nile connect logout - End current session
  • nile config - Configure CLI settings
  • nile workspace list - List available workspaces