Commands on Raven

setup

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

raven sync-jobs #

Download openjobdata daily deltas into a local SQLite index.

Usage #

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

What it does #

Syncs companies registry from HuggingFace bucket
Downloads recent daily parquet deltas
Upserts into data/jobs.db
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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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

Mon, 01 Jan 0001 00:00:00 +0000

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.

Commands on Raven

setup

raven setup #

discover

raven discover #

Usage #

Behavior #

Flags #

Output JSON shape #

Tips #

draft

raven draft #

Usage #

Input sources #

Output files #

CSV columns #

Flags #

Application types #

Form (application_type: form) #

send

raven send #

Prerequisites #

Usage #

Required CSV columns #

sync-jobs

raven sync-jobs #

Usage #

What it does #

Environment #

After sync #

Flags #

scan-ats

raven scan-ats #

scan-boards

raven scan-boards #

query

raven query #

auth-gmail / auth-outlook

OAuth setup #

Gmail #

Outlook #

Send #

Form (`application_type: form`) #