Checkly Auth

checkly auth

Manage Checkly CLI authentication.

Quick start

# Interactive login (browser-based)
npx checkly login

# Check authentication status
npx checkly whoami

# Switch to a known account in multi-account setups
npx checkly switch --account-id <account-id>

# Log out of saved local-session credentials
npx checkly logout

# Manual configuration (for CI/CD)
export CHECKLY_API_KEY="your-api-key"
export CHECKLY_ACCOUNT_ID="your-account-id"

Authentication methods

Interactive login (recommended for local development)

npx checkly login

Opens browser to authenticate and automatically saves credentials to your system config.

Credential storage location:

• Linux/macOS: ~/.config/@checkly/cli/config.json
• Windows: %APPDATA%\@checkly\cli\config.json

Environment variables (recommended for CI/CD)

export CHECKLY_API_KEY="cu_abc123..."
export CHECKLY_ACCOUNT_ID="12345"

# Test authentication
npx checkly whoami

Getting your credentials:

1. Log into app.checklyhq.com
2. Navigate to Account Settings → API Keys
3. Create new API key with appropriate permissions
4. Copy Account ID from URL or account settings

Environment variables take precedence over saved npx checkly login credentials. npx checkly whoami tells you when the active account is resolved from CHECKLY_API_KEY / CHECKLY_ACCOUNT_ID, and npx checkly logout warns if those env vars still keep you authenticated after local session cleanup.

Configuration file (manual)

Create/edit config file at ~/.config/@checkly/cli/config.json:

{
  "apiKey": "cu_abc123...",
  "accountId": "12345"
}

Workflows

First-time setup

1. Sign up for Checkly account (if needed):

   # Opens signup page
   npx checkly login
   

2. Authenticate CLI:

   npx checkly login
   

3. Verify authentication:

   npx checkly whoami
   

   Expected output:

   Logged in as john@example.com
   Account: Acme Corp (ID: 12345)
   

4. Initialize project:

   npm create checkly@latest
   

Switching accounts

If you have multiple Checkly accounts:

1. List or verify the current account:

   npx checkly whoami
   

2. Switch directly when you know the target account ID:

   npx checkly switch --account-id <account-id>
   

3. If you need a fresh browser login, clear saved local-session credentials first:

   npx checkly logout --force
   npx checkly login
   

4. Verify the selected account:

   npx checkly whoami
   

If CHECKLY_API_KEY or CHECKLY_ACCOUNT_ID are set in the shell or a project .env, they override the saved account. Remove or update those variables before using login / switch to change the effective account.

CI/CD authentication

For automated pipelines (GitHub Actions, GitLab CI, etc.):

1. Create API key in Checkly UI:

   • Navigate to Account Settings → API Keys
   • Click "Create API Key"
   • Name: "CI/CD Pipeline"
   • Permissions: Read/Write (for deploy)
   • Copy the key (starts with cu_)

2. Add secrets to CI/CD platform:

   • CHECKLY_API_KEY: Your API key
   • CHECKLY_ACCOUNT_ID: Your account ID

3. Use in pipeline:

   # GitHub Actions example
   - name: Test checks
     env:
       CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
       CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }}
     run: npx checkly test
   
   - name: Deploy checks
     env:
       CHECKLY_API_KEY: ${{ secrets.CHECKLY_API_KEY }}
       CHECKLY_ACCOUNT_ID: ${{ secrets.CHECKLY_ACCOUNT_ID }}
     run: npx checkly deploy --force
   

Troubleshooting

"Could not find Checkly credentials"

Cause: No authentication configured

Solution:

# Option 1: Interactive login
npx checkly login

# Option 2: Set environment variables
export CHECKLY_API_KEY="your-key"
export CHECKLY_ACCOUNT_ID="your-account-id"

whoami still shows an account after logout

Cause: CHECKLY_API_KEY or CHECKLY_ACCOUNT_ID are still set in the shell or loaded from a project .env. npx checkly logout can clear saved local-session credentials but cannot remove environment variables.

Solution:

# Inspect environment-backed credentials without printing secret values
env | grep '^CHECKLY_.*=' | sed 's/=.*$/=<set>/'

# Unset for the current shell if you want to use browser login credentials instead
unset CHECKLY_API_KEY CHECKLY_ACCOUNT_ID
npx checkly whoami

"401 Unauthorized"

Possible causes:

• API key has been deleted or revoked
• API key doesn't have required permissions
• Account ID doesn't match API key

Solution:

1. Verify credentials:

   npx checkly whoami
   

2. If invalid, re-authenticate:

   npx checkly login
   

3. For CI/CD, regenerate API key in Checkly UI

"Account not found"

Cause: Account ID is incorrect

Solution:

1. Log into app.checklyhq.com
2. Check URL: app.checklyhq.com/accounts/{ACCOUNT_ID}/...
3. Or check Account Settings → Account ID
4. Update CHECKLY_ACCOUNT_ID environment variable

Permission errors during deploy

Cause: API key has read-only permissions

Solution:

1. Go to Account Settings → API Keys in Checkly UI
2. Create new API key with "Read/Write" permissions
3. Update your API key

Environment variables reference

CHECKLY_MQTT_URL is advanced troubleshooting configuration for local or custom setups where test-session event streams come from a different broker. It is analogous to CHECKLY_API_URL for local endpoint overrides, not a normal hosted Checkly credential or default CI setting.

Security best practices

Local development

• ✅ Use npx checkly login (credentials stored securely)
• ✅ Add config file to .gitignore (if using manual config)
• ❌ Don't commit API keys to version control

CI/CD pipelines

• ✅ Store credentials as encrypted secrets
• ✅ Use API keys with minimal required permissions
• ✅ Rotate API keys regularly
• ❌ Don't log API keys in pipeline output

API key management

• ✅ Create separate API keys for different purposes (CI/CD, local dev)
• ✅ Name keys descriptively ("GitHub Actions Deploy", "John's Laptop")
• ✅ Revoke unused or compromised keys immediately
• ❌ Don't share API keys between team members

Related Skills

Next steps after authentication:

• See checkly-config to configure your project
• See checkly-test to run checks locally
• See checkly-deploy to deploy checks to Checkly

Project setup:

• New project: Use npm create checkly@latest (includes auth setup)
• Existing project: Install checkly package and authenticate