Troubleshoot Authentication

Fix common authentication issues with the CLI.

Solutions for the most common authentication problems.

Authentication Methods

The CLI supports two auth methods:

Method	Use Case	Storage
Consuelo SDK OAuth	CRM integration, full platform	Browser login, auto-refresh
API Key	Automation, scripts	Config file or env var

Common Issues

”Authentication failed” on auth:login

Cause: OAuth flow couldn’t complete

Solutions:

1. Check browser isn’t blocking popups
2. Clear browser cookies and retry
3. Verify your internet connection
4. Ensure no firewall blocking consuelo.consuelohq.com

# Retry login
consuelo auth:login

# If stuck, logout first
consuelo auth:logout
consuelo auth:login

”Token expired”

Cause: OAuth token expired and couldn’t refresh

Solutions:

# Re-authenticate
consuelo auth:logout
consuelo auth:login

Tokens typically last 24 hours. The CLI auto-refreshes, but manual re-login may be needed if you haven’t used the CLI in a while.

”Invalid API key”

Cause: API key is incorrect or revoked

Solutions:

1. Verify the key is correct:
   consuelo config get apiKey --show-sensitive
   
2. Check key hasn’t been revoked in your workspace settings
3. Generate a new API key in the dashboard
4. Update config:
   consuelo config set apiKey your_new_api_key
   

“Workspace not found”

Cause: Workspace ID is invalid or you don’t have access

Solutions:

1. Verify workspace ID:
   consuelo config get workspaceId
   
2. List available workspaces (requires auth):
   consuelo workspace list
   
3. Set correct workspace:
   consuelo config set workspaceId your_workspace_id
   

“Unauthorized” on API calls

Cause: Credentials missing or invalid

Solutions:

1. Check auth status:
   consuelo status
   
2. Verify API key or OAuth is configured
3. Try re-authenticating:
   consuelo auth:login
   

“Browser didn’t open”

Cause: CLI can’t open default browser

Solutions:

1. Open the URL manually (shown in terminal output)

2. Set browser explicitly:

   # macOS
   open "https://consuelo.consuelohq.com/auth/cli"
   
   # Linux
   xdg-open "https://consuelo.consuelohq.com/auth/cli"
   
   # Windows
   start "https://consuelo.consuelohq.com/auth/cli"
   

“Callback timeout”

Cause: OAuth callback didn’t complete within 5 minutes

Solutions:

1. Complete the login flow faster
2. Check browser isn’t slow or hanging
3. Retry the login:
   consuelo auth:login
   

Two Config Systems

The CLI has two configuration systems that coexist:

Legacy (CliConfig)

Used for Twilio, AI keys, basic settings.

Modern (ConsuloConfig)

Used for full config structure.

If you have issues:

# View current config
consuelo config list

# Check for conflicts
consuelo config validate

Switch Auth Methods

From OAuth to API Key

# Set API key
consuelo config set apiKey your_api_key

# Clear OAuth tokens
consuelo auth:logout

From API Key to OAuth

# Remove API key
consuelo config unset apiKey

# Login via OAuth
consuelo auth:login

Environment Variables

Environment variables override config:

# Force API URL
export CONSUELO_API_URL=https://staging.consuelohq.com

# Set API key
export CONSUELO_API_KEY=your_api_key

# Set workspace
export CONSUELO_WORKSPACE_ID=your_workspace_id

Environment variables take precedence over config files. If auth isn’t working, check for conflicting env vars.

Clear All Auth

Start fresh:

# Logout
consuelo auth:logout

# Remove config
rm ~/.consuelo/config.json

# Remove environment variables
unset CONSUELO_API_KEY
unset CONSUELO_API_URL
unset CONSUELO_WORKSPACE_ID

# Re-initialize
consuelo init

Check Auth Status

consuelo status

Output shows:

Configuration: ~/.consuelo/config.json
Auth Method: oauth (Twenty SDK)
API URL: https://consuelo.consuelohq.com
Workspace: acme-corp (uuid)
Status: ✓ Connected

Contact Support

If issues persist:

1. Run with verbose output:
   consuelo --verbose auth:login
   
2. Check logs:
   cat ~/.consuelo/debug.log
   
3. Contact support with:
   • Error message
   • Verbose output
   • Config (redact sensitive values)

Next Steps

• Getting Started — Set up authentication
• Configuration — Manage config files
• CLI FAQ — More troubleshooting