Commands #

Full CLI reference for every raven subcommand. Run ./raven <command> --help anytime for flags.

Pages in this section #

setup

raven setup #

First-time installation and config seeding.

raven setup

Installs npm dependencies (root + jobs/) and creates:

• .env from .env.example
• config/portals.yml from example
• config/profile.yml from example
• config/outreach.yml from example
• files/resume.md from example

Safe to re-run — existing files are not overwritten.

discover

raven discover #

Unified job search across ATS APIs, board feeds, and optional local index.

Architecture: How discovery works — tiers, reverse ATS scan, WebSearch status.

Usage #

raven discover [options]
raven discover --q "backend engineer" --loc Remote --since 7
raven discover --sources boards --since 7
raven discover --json

Behavior #

• Not open-web search — fetches public JSON APIs and board feeds (see how it works)
• Loads title/location filters from config/portals.yml by default
• CLI flags (--q, --loc, …) extend config filters
• Runs tiers in parallel
• Deduplicates by canonical job URL
• Auto-saves results to data/jobs.json (unless --no-save)
• Prints Next: raven draft --max 25 when complete

Flags #

Flag	Description	Default
--q "keywords"	Title must match (comma-separated)	from portals.yml
--not "words"	Title must not contain	from portals.yml
--loc Remote,EU	Location allow-list	from portals.yml
--noloc "X"	Location block-list	from portals.yml
--home "City"	Location always-allow	—
--since N	Postings from last N days	7
--sources	ats, boards, index, hiringcafe	ats,boards,index
--ats	Subset of ATS platforms	all 12
--limit N	Max companies per ATS	150
--max N	Max total results	1000
--save PATH	Custom save path	data/jobs.json
--no-save	Skip writing JSON	—
--json	Machine-readable stdout	—
--stream	NDJSON stream (for tooling)	—
--verbose	Extra tier/child logs	—
--quiet	Summary only	—
--no-log	Disable data/logs/ file	—

Output JSON shape #

{
  "count": 42,
  "rawMatches": 120,
  "deduped": 78,
  "offers": [
    {
      "url": "https://…",
      "company": "Acme",
      "title": "Backend Engineer",
      "location": "Remote",
      "postedAt": "2026-07-04",
      "ats": "greenhouse",
      "source": "greenhouse-full"
    }
  ],
  "savedAt": "2026-07-04T08:47:54.000Z"
}

Tips #

• Always set title filters in portals.yml — empty filters match every job
• Use --sources boards for quick tests (~3s vs ~1min full scan)
• Run raven sync-jobs before using --sources index

See Job sources for platform details.

draft

raven draft #

Generate tailored application drafts from discovered jobs.

Usage #

raven draft --max 25
raven draft --input data/jobs.json --max 25
raven draft --q "backend engineer" --since 7 --max 20
raven draft --gemini

Input sources #

Method	Command
Latest discover (default)	raven draft → reads data/jobs.json
Explicit file	raven draft --input data/jobs.json
Inline discover + draft	raven draft --q "engineer" --since 7

Output files #

File	Purpose
drafts/outreach-YYYY-MM-DD.csv	Spreadsheet — review, edit, send
drafts/outreach-YYYY-MM-DD.md	Human-readable review
drafts/outreach-YYYY-MM-DD.xlsx	Optional (--xlsx)

CSV columns #

Column	Description
application_type	email or form
application_label	Human label
contact_email	For email rows (often blank — fill manually)
subject	Email subject or form title
body	Email body or short form guide
company, title, job_url	Job metadata
jd_keywords	Terms extracted from job title
action_words	Suggested verbs for this role
tailored_bullets	Resume bullets matched to JD
form_steps	Full ATS guide (form jobs)
links_block	Your portfolio/GitHub/LinkedIn line
ai_draft	yes, no, or fallback
disclaimer	Review-before-submit reminder

Flags #

Flag	Description
--input PATH	Jobs JSON (default: data/jobs.json)
--max N	Max drafts to generate
--gemini	AI-polish email drafts (needs GEMINI_API_KEY)
--guess-email	Suggest careers@ from apply URL domain
--refresh-resume	Re-parse resume (ignore cache)
--xlsx	Also write Excel
--no-markdown	Skip .md review file
--output PATH	Custom output base path

Application types #

Form (application_type: form) #

Greenhouse, Lever, Ashby, Workday, and similar ATS listings. Raven generates step-by-step guides with your links and tailored bullets — not sendable email.

send

raven send #

Send outreach emails from a CSV or XLSX file via Gmail or Outlook.

Prerequisites #

raven auth-gmail    # or auth-outlook

Configure in .env:

SENDER_NAME=Your Name
SENDER_EMAIL=you@example.com
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…
GMAIL_REFRESH_TOKEN=…

Usage #

raven send --input drafts/outreach-2026-07-04.csv --dry-run
raven send --input drafts/outreach-2026-07-04.csv --delay 60 --limit 20
raven send --provider outlook --input contacts.xlsx

Required CSV columns #

Column	Description
contact_email	Recipient (or email)
subject	Email subject
body	Plain-text body

Extra columns (company, job_url, etc.) are ignored by the sender.

sync-jobs

raven sync-jobs #

Download openjobdata daily deltas into a local SQLite index.

Usage #

raven sync-jobs
raven sync-jobs --days 3

What it does #

1. Syncs companies registry from HuggingFace bucket
2. Downloads recent daily parquet deltas
3. Upserts into data/jobs.db
4. Exports ATS company slug lists to data/cache/ats-companies/

Environment #

If you get HTTP 401:

# .env
HF_TOKEN=hf_xxxxxxxx

After sync #

raven discover --sources index --q "engineer"
raven query --q "ML engineer" --since 7

Flags #

Flag	Description
--days N	Number of daily deltas to fetch
--full	Full backfill (slow)
--no-export-ats	Skip ATS slug export

See openjobdata for details.

scan-ats

raven scan-ats #

Live ATS reverse scan only (without board feeds or index).

raven scan-ats --q "software engineer" --since 7
raven scan-ats --ats greenhouse,lever,ashby --json
raven scan-ats --use-portals --dry-run

Uses filters from CLI flags or --use-portals to read config/portals.yml directly.

Platforms: Greenhouse, Lever, Ashby, Workday, Rippling, Workable, BambooHR, SmartRecruiters, Recruitee, Pinpoint, Teamtailor, Personio.

For unified search, prefer raven discover --sources ats.

scan-boards

raven scan-boards #

Board feed scan only (RemoteOK, Remotive, Arbeitnow, Landing.jobs).

raven scan-boards --q "software engineer"
raven scan-boards --q engineer --loc Remote --json

Faster than full ATS walk — good for remote-first roles.

For unified search, prefer raven discover --sources boards.

query

raven query #

Search the local openjobdata SQLite index.

raven query --q "software engineer" --since 7
raven query --q "designer" --ats greenhouse,lever --json

Requires data/jobs.db from raven sync-jobs.

Same filter semantics as discover (--q, --not, --loc, --since, --ats, --max).

auth-gmail / auth-outlook

OAuth setup #

One-time OAuth for email sending.

Gmail #

# Set in .env first:
# GOOGLE_CLIENT_ID=
# GOOGLE_CLIENT_SECRET=

raven auth-gmail

Saves GMAIL_REFRESH_TOKEN to .env.

Outlook #

# Set in .env first:
# MS_CLIENT_ID=
# MS_CLIENT_SECRET=

raven auth-outlook

Saves refresh token to .env.

Send #

raven send --provider gmail --input drafts/outreach.csv --dry-run
raven send --provider outlook --input drafts/outreach.csv

See Environment variables for all .env keys.

Command map #

Typical workflow #

./raven setup
./raven discover --q "software engineer" --since 7
./raven draft --max 25
./raven send --input drafts/outreach-2026-07-04.csv --dry-run

Logging flags (all job commands) #

Start with discover →