Connecting to Nile

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

Related Commands

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