CLI Authentication

How to use the bloqr-compiler CLI with authenticated API endpoints.

Overview

When the CLI operates in queue mode (--use-queue), it submits compilation jobs to the remote worker API instead of compiling locally. The worker API enforces authentication and rate limiting, so you must supply credentials via CLI flags.

Local-only compilation (no --use-queue) does not require authentication — it reads local files and URLs directly.

Authentication Flags

Mutual Exclusion

--api-key and --bearer-token are mutually exclusive — you must choose one authentication method per invocation. If both are provided, the Zod schema validation rejects the input with:

Cannot specify both --api-key and --bearer-token; choose one authentication method

Validation Rules

Usage Examples

Compile via Queue with an API Key

bloqr-compiler -c config.json -o output.txt \
  --use-queue \
  --api-key blq_Xk9mP2nLqR5tV8wZ...

Compile via Queue with a Clerk JWT

# Obtain a JWT from the web UI (DevTools → Network → copy Authorization header)
bloqr-compiler -c config.json -o output.txt \
  --use-queue \
  --bearer-token eyJhbGciOiJSUzI1NiIs...

Use a Custom API URL (Local Development)

bloqr-compiler -c config.json -o output.txt \
  --use-queue \
  --api-key blq_Xk9mP2nLqR5tV8wZ... \
  --api-url http://localhost:8787

Combine Auth with Other Flags

bloqr-compiler \
  -i https://example.org/hosts.txt \
  -o output.txt \
  --use-queue \
  --api-key blq_Xk9mP2nLqR5tV8wZ... \
  --priority high \
  --verbose \
  --benchmark

Obtaining Credentials

API Key (Recommended for CLI / CI)

API keys are long-lived and ideal for scripts, CI/CD pipelines, and CLI usage.

1. Sign in to the web UI at https://api.bloqr.dev/

2. Navigate to Settings → API Keys

3. Click "Create API Key"

4. Select scopes:

   • compile — Required for /compile, /compile/stream, /compile/batch
   • rules — Required for /rules CRUD endpoints
   • admin — Required for /admin/* endpoints

5. Copy the key immediately — it is shown only once

6. Store it securely (environment variable, secrets manager, etc.)

See API Authentication for full details on API key management.

Clerk JWT (Browser-Derived)

Clerk JWTs are short-lived (~60 seconds) and best suited for one-off testing:

1. Sign in to the web UI

2. Open browser DevTools → Console

3. Run:

   window.Clerk?.session?.getToken().then(t => console.log(t));
   

4. Copy the printed eyJ... token

5. Pass it via --bearer-token

Tip: For automated or repeated CLI usage, prefer API keys over Clerk JWTs.

CI/CD Integration

GitHub Actions

- name: Compile filter list
  run: |
    bloqr-compiler -c config.json -o output.txt \
      --use-queue \
      --api-key ${{ secrets.ADBLOCK_API_KEY }}

Environment Variable Pattern

Store the API key in an environment variable to avoid passing it on the command line:

export ADBLOCK_API_KEY="blq_Xk9mP2nLqR5tV8wZ..."

bloqr-compiler -c config.json -o output.txt \
  --use-queue \
  --api-key "$ADBLOCK_API_KEY"

Rate Limiting

When using queue mode, the worker API enforces rate limits based on the authenticated user's tier:

If rate-limited, the CLI receives a 429 Too Many Requests response. The response includes Retry-After and X-RateLimit-* headers.

Error Handling

Security Best Practices

• Never commit API keys to source control — use environment variables or a secrets manager
• Rotate keys regularly — create keys with expiration dates (1–365 days)
• Use minimum scopes — only grant the scopes your workflow needs (e.g., compile for CI builds)
• Prefer API keys over JWTs for CLI usage — JWTs expire quickly and require browser interaction to obtain
• Use --api-url carefully — only point to trusted endpoints; the CLI sends your credentials to this URL

Further Reading

• CLI Reference — Full CLI option reference
• API Authentication Guide — Detailed auth method reference
• Postman Testing — Testing authenticated APIs with Postman
• Configuration Guide — Environment variables and secrets management
• Removing Anonymous Access — Migration timeline