@pulspeed/cli

CLI for Pulspeed — scan websites, check Core Web Vitals, and detect regressions from the terminal or CI/CD.

Install

# Run without installing (npx)
npx @pulspeed/cli scan https://example.com

# Or install globally
npm install -g @pulspeed/cli

Authentication

Set your API key as an environment variable:

export PULSPEED_API_KEY=your_key_here

Get your key at pulspeed.ai/settings/tokens.

Commands

scan — Scan a URL

pulspeed scan https://example.com
pulspeed scan https://example.com --strategy=desktop
pulspeed scan https://example.com --budget=80   # exit 1 if score < 80
pulspeed scan https://example.com --async        # dispatch without waiting

Options:

• --strategy=mobile|desktop — default: mobile
• --budget=N — fail (exit code 1) if performance score is below N
• --async — dispatch scan and print job ID without waiting

bulk — Scan multiple URLs

pulspeed bulk https://example.com https://example.com/about https://example.com/blog
pulspeed bulk https://example.com https://example.com/about --strategy=desktop

Returns a batch_id to check progress with pulspeed batch.

batch — Check bulk scan status

pulspeed batch batch_abc123

metrics — View score history

pulspeed metrics https://example.com
pulspeed metrics https://example.com --period=30d

Options:

• --period=7d|30d|90d — default: 7d

sites — List monitored sites

pulspeed sites

usage — Check API usage

pulspeed usage

Shows scans and AI analyses used vs. plan limits.

job — Check a scan job

pulspeed job 42

CI/CD Integration

GitHub Actions

- name: Performance Budget Check
  env:
    PULSPEED_API_KEY: ${{ secrets.PULSPEED_API_KEY }}
  run: npx @pulspeed/cli scan ${{ env.STAGING_URL }} --budget=80

Exit codes

• 0 — success (or score meets budget)
• 1 — error (API error, auth failure, or score below budget)

License

MIT — pulspeed.ai