# Checkly Auth

> Manage Checkly CLI authentication including login/logout, check auth status, and configure API credentials. Use when setting up Checkly CLI for first time, troubleshooting auth issues, or switching Checkly accounts. Triggers on checkly login, checkly logout, authentication, API key, account ID, credentials.

- Skill: `vince-winkintel/checkly-auth` (Agent Skill)
- Install (CLI): `npx skillmds add vince-winkintel/checkly-auth`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vince-winkintel/checkly-auth/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: vince-winkintel (https://skillmd.com/u/vince-winkintel)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/vince-winkintel/checkly-auth

---


# checkly auth

Manage Checkly CLI authentication.

## Quick start

```bash
# 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)

```bash
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)

```bash
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](https://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`:

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

## Workflows

### First-time setup

1. **Sign up for Checkly account** (if needed):
   ```bash
   # Opens signup page
   npx checkly login
   ```

2. **Authenticate CLI**:
   ```bash
   npx checkly login
   ```

3. **Verify authentication**:
   ```bash
   npx checkly whoami
   ```

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

4. **Initialize project**:
   ```bash
   npm create checkly@latest
   ```

### Switching accounts

If you have multiple Checkly accounts:

1. **List or verify the current account**:
   ```bash
   npx checkly whoami
   ```

2. **Switch directly when you know the target account ID**:
   ```bash
   npx checkly switch --account-id <account-id>
   ```

3. **If you need a fresh browser login, clear saved local-session credentials first**:
   ```bash
   npx checkly logout --force
   npx checkly login
   ```

4. **Verify the selected account**:
   ```bash
   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**:
   ```yaml
   # 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**:
```bash
# 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**:
```bash
# 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:
   ```bash
   npx checkly whoami
   ```

2. If invalid, re-authenticate:
   ```bash
   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](https://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

| Variable | Required | Description |
|----------|----------|-------------|
| `CHECKLY_API_KEY` | Yes | API key (starts with `cu_`) |
| `CHECKLY_ACCOUNT_ID` | Yes | Numeric account ID |
| `CHECKLY_API_URL` | No | Override the local API URL when `CHECKLY_ENV=local` (default: `http://127.0.0.1:3000`) |
| `CHECKLY_MQTT_URL` | No | Override the local events/MQTT broker when `CHECKLY_ENV=local` |
| `CHECKLY_SKIP_AUTH` | No | Skip authentication (for debugging flags) |

`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