Skip to main content

Installation & Setup

Use this guide for first-time setup: install Snoopy, configure your OpenRouter key, add your first job, and verify everything is healthy.

Requirements​

  • Node.js 20+
  • npm 10+
  • OpenRouter API key (required for qualification)

Without an OpenRouter key, job runs will fail when Snoopy reaches qualification.

Install Snoopy​

From npm (recommended):

npm install -g snoopy-cli
snoopy --help

From source (development builds):

npm install
npm run build
npm link
snoopy --help

Configure OpenRouter API Key​

Set your key with the interactive settings flow:

snoopy settings

Navigate to OpenRouter API Key, paste your key, then save.

Storage behavior:

  • Snoopy stores secrets in your OS keychain when available.
  • If keychain storage is unavailable, Snoopy uses an encrypted fallback at ~/.snoopy/secrets.enc.

If the key is missing, snoopy job add prompts for it automatically during first-time setup.

Add Your First Job​

Start the guided job flow:

snoopy job add

What the flow does:

  • Collects your monitoring intent and follow-up details
  • Generates a job name, slug, and qualification prompt
  • Saves the job locally
  • Runs an immediate first scan
  • Enables scheduled execution after that first run attempt completes

You can also use the short alias:

snoopy add

After setup, list your jobs:

snoopy jobs list

To run a quick validation scan with a cap:

snoopy job run --limit 5
snoopy job run <jobRef> --limit 5

Verify Setup​

Run health checks:

snoopy doctor

Confirm at least:

  • OpenRouter API key is configured
  • Database and filesystem checks pass

First-Time Command Sequence​

If you want the full setup path in one place:

# 1) Install globally
npm install -g snoopy-cli

# 2) Optional: configure key before creating jobs
snoopy settings

# 3) Create first job (prompts for missing key/settings as needed)
snoopy job add

# 4) Verify health
snoopy doctor