Checkly Auth

checkly auth

Manage Checkly CLI authentication.

Quick start

# Interactive login (browser-based)
npx checkly login

# Check authentication status
npx checkly whoami

# 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

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. Logout from current account:

   # Manual logout (delete config)
   rm ~/.config/@checkly/cli/config.json
   

2. Login to different account:

   npx checkly login
   

3. Verify new account:

   npx checkly whoami
   

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"

"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

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