Raven

How discovery works

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

How job discovery works #

Deep dive: architecture, data flow, and what Raven does not do.

Module: jobs/discover.mjs · CLI: raven discover

TL;DR #

raven discover does not search Google or scrape arbitrary websites. It runs up to four parallel tiers that pull structured job data from public APIs and feeds, filters client-side, deduplicates by canonical apply URL, and saves to data/jobs.json.

flowchart LR
 A[raven discover] --> B[ATS APIs]
 A --> C[Board feeds]
 A --> D[Local SQLite]
 A --> E[hiring.cafe optional]
 B --> F[merge + dedup]
 C --> F
 D --> F
 E --> F
 F --> G[data/jobs.json]

What “search” means #

Mechanism	How listings are found	Default discover?
ATS reverse scan	Public JSON API per company board	Yes
Board feeds	Aggregator APIs (RemoteOK, Remotive, …)	Yes
openjobdata index	SQL on `data/jobs.db`	Yes (needs sync)
hiring.cafe	POST search API	Opt-in
WebSearch / `search_queries`	Google-style `site:` queries	Not implemented
`scan_method: websearch`	Per-company handoff	Log only

Zero LLM, zero browser by default.

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.

Architecture

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

Architecture #

Raven is a bash CLI (bin/raven) that dispatches to shell scripts (scripts/*.sh), which invoke a Node.js discovery engine (jobs/).

┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ bin/raven │────▶│ scripts/*.sh │────▶│ jobs/*.mjs │
│ (CLI) │ │ (_lib.sh) │ │ (ESM engine) │
└─────────────┘ └──────────────┘ └─────────────────┘
 │ │
 ▼ ▼
 config/*.yml data/jobs.json
 .env data/jobs.db
 files/resume.md drafts/

Layers #

CLI layer (`bin/raven`, `scripts/`) #

Resolves repo root (works with npm link)
Loads .env
Ensures dependencies installed
Forwards to Node scripts or bash helpers

Discovery engine (`jobs/`) #

Module	Role
`discover.mjs`	Orchestrates parallel tier scans
`scan-ats-full.mjs`	Reverse ATS walk (12 platforms)
`scan.mjs`	Board feeds + portal scanner
`sync-openjobdata.mjs`	HuggingFace → SQLite index
`query-index.mjs`	Search local index
`draft-outreach.mjs`	Application draft CLI
`lib/draft-engine.mjs`	Profile + resume + form guides
`plugins/gemini-draft.mjs`	Optional Gemini email polish

Providers (`jobs/providers/`) #

One module per ATS or board feed. Each exports { id, fetch, detect? } and uses shared HTTP helpers.

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.

Installation

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

Installation #

Requirements #

Requirement	Version	Notes
Node.js	18+	Required
npm	bundled with Node	Required
Git	any	Clone the repository

Optional:

Gmail or Microsoft OAuth credentials for raven send
GEMINI_API_KEY for raven draft --gemini
HF_TOKEN (HuggingFace) if openjobdata sync returns HTTP 401

Clone and setup #

From the Raven repository root:

git clone <your-raven-repo-url> raven
cd raven
./raven setup

raven setup runs:

npm install in the repo root
npm install in jobs/
Creates starter config from examples (if missing):

File	Purpose
`.env`	Sender identity, API keys, OAuth tokens
`config/portals.yml`	Job search filters
`config/profile.yml`	Identity, links, resume path
`files/resume.md`	Starter resume (replace with yours)

Install `raven` globally (optional) #

npm link
raven --help

Without npm link, use ./raven from the repo root.

Logging

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

Logging #

All Raven job commands emit live progress and write timestamped log files.

Default behavior #

Progress phases printed to stdout
Summary line with counts and elapsed time
Log file written to data/logs/

Example log paths:

data/logs/discover-2026-07-04T08-30-00.log
data/logs/draft-2026-07-04T08-35-12.log
data/logs/sync-jobs-2026-07-04T07-00-00.log
data/logs/send-2026-07-04T09-00-00.log

Flags #

Flag	Effect
(default)	Live progress + log file
`--verbose`	Extra detail (per-ATS logs during discover)
`--quiet`	One-line summary only
`--no-log`	Disable log file (stdout only)

Commands with logging #

raven discover
raven draft
raven sync-jobs
raven scan-ats / scan-boards
raven query
raven send

Log contents #

Typical discover log:

portals.yml

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

portals.yml #

config/portals.yml controls what jobs Raven considers relevant when you run raven discover without explicit --q / --loc flags.

How discover uses it #

When you run bare raven discover:

Raven loads config/portals.yml (or path from RAVEN_PORTALS in .env)
Title keywords from title_filter.positive become --q filters
Negative keywords become --not filters
Location rules from location_filter become --loc / --noloc

CLI flags override portals config when provided:

# Uses portals.yml filters
raven discover

# Ignores portals title filter — uses CLI only
raven discover --q "backend engineer" --loc Remote

Minimal example #

title_filter:
 positive:
 - "software engineer"
 - "backend"
 - "developer"
 - "intern"
 negative:
 - "nurse"
 - "sales"
 - "Junior"

location_filter:
 allow:
 - "Remote"
 - "India"
 block:
 - "On-site only"

Title filter semantics #

At least one positive keyword must match the job title (case-insensitive substring)
Zero negative keywords may match
Empty positive list = match all titles (use negatives to exclude)

Location filter semantics #

Applied in order:

Resume parsing

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

Resume parsing #

Raven parses your resume from config/profile.yml → resume.path and caches structured bullets and skills.

Supported formats #

Format	Notes
`.md`	Best — use `## Experience` with `-` bullet lines
`.txt`	Bullet lines + optional `Skills:` line
`.pdf`	Requires `pdf-parse` (installed via `raven setup`)

Markdown structure #

# Your Name

## Experience

### Company A — Role Title
- Built X using Y, achieving Z
- Led migration of ...

### Company B — Role Title
- Shipped feature that ...

## Skills

JavaScript, TypeScript, Node.js, React, PostgreSQL

Parsing rules #

Sections detected by ## Heading (H2)
Bullets under ## Experience (including ### subheadings) are extracted
Skills from ## Skills section or comma-separated line
highlights and skills in profile.yml override parser output when set

Cache #

Parsed output is cached at data/cache/resume-parsed.json for speed.

Sources & tiers

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

Job sources #

Raven orchestrates discovery tiers in parallel via jobs/discover.mjs. Each tier uses public APIs or feeds — not web search engines.

Full architecture: How discovery works · WebSearch status: Scan strategies

Tier 1 — Live ATS APIs (`--sources ats`) #

Reverse-scans public company directories and hits each platform’s zero-auth JSON API.

Platform	Careers URL pattern
Greenhouse	`job-boards.greenhouse.io/{slug}`
Lever	`jobs.lever.co/{slug}`
Ashby	`jobs.ashbyhq.com/{slug}`
Workday	`{tenant}.wd{N}.myworkdayjobs.com/{site}`
Rippling	`ats.rippling.com/{slug}/jobs`
Workable	`apply.workable.com/{slug}`
BambooHR	`{tenant}.bamboohr.com/careers`
SmartRecruiters	`careers.smartrecruiters.com/{slug}`
Recruitee	`{slug}.recruitee.com`
Pinpoint	`{slug}.pinpointhq.com`
Teamtailor	`{slug}.teamtailor.com`
Personio	`{slug}.jobs.personio.de`

Company slug lists come from openjobdata (after raven sync-jobs) or bundled caches in data/cache/ats-companies/.

Workflow

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

Outreach workflow #

End-to-end flow from discovery to sent email.

1. Discover #

raven discover --q "backend engineer" --loc Remote --since 7

Results save to data/jobs.json.

2. Draft #

raven draft --max 25

Creates:

File	Purpose
`drafts/outreach-YYYY-MM-DD.csv`	Spreadsheet with all columns
`drafts/outreach-YYYY-MM-DD.md`	Human-readable review

Optional: --xlsx for Excel, --gemini for AI polish.

3. Review #

Open the markdown file:

open drafts/outreach-*.md # macOS

Check each entry:

email rows — subject, body, disclaimer
form rows — follow form_steps in browser (skip send)

Edit CSV directly if needed before sending.

Scan strategies

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

Scan strategies #

portals.example.yml documents a 4-level strategy for job discovery beyond default tiers. This page maps each level to what Raven runs automatically today.

Four levels (from portals.example.yml) #

Level 0. local_parser → custom script per company
Level 1. Playwright → browser scrape of careers_url
Level 2. HTTP JSON → public ATS/board APIs (providers)
Level 3. WebSearch → site: filtered search queries

Default raven discover uses HTTP JSON at scale (ATS reverse scan + board feeds) — not levels 0–1 per company, and not level 3.

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.

File layout

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

Repository layout #

raven/
├── bin/raven # CLI entry (npm link → global raven)
├── raven # Symlink to bin/raven
├── scripts/ # Bash wrappers (_lib.sh, discover.sh, draft.sh, …)
├── jobs/ # Node.js job engine
│ ├── discover.mjs # Unified discovery orchestrator
│ ├── draft-outreach.mjs # Draft orchestrator
│ ├── lib/ # Shared modules (profile, resume, log, portals, …)
│ └── plugins/ # Optional plugins (gemini-draft.mjs)
├── config/
│ ├── portals.example.yml
│ ├── profile.example.yml
│ └── outreach.example.yml
├── files/
│ └── resume.example.md # Template resume
├── data/ # Gitignored runtime data
│ ├── jobs.json # Latest discover results
│ ├── jobs.db # openjobdata SQLite index
│ ├── cache/ # Resume parse cache, ATS slug lists
│ └── logs/ # Command logs
├── drafts/ # Generated outreach CSV/MD/XLSX
├── docs/ # Markdown docs (source for this site)
└── raven-web-docs/ # Hugo documentation site

Tracked vs gitignored #

Tracked (committed)	Gitignored (local)
`*.example.yml`	`config/profile.yml`
`files/resume.example.md`	`config/portals.yml`
Source code	`config/outreach.yml`
	`files/resume.md`
	`data/*.json`, `data/jobs.db`
	`data/logs/`, `data/cache/`
	`drafts/outreach-*`
	`.env`

Key data files #

Path	Created by	Purpose
`data/jobs.json`	`raven discover`	Latest job matches (default draft input)
`data/jobs.db`	`raven sync-jobs`	Local openjobdata index
`data/cache/resume-parsed.json`	`raven draft`	Parsed resume cache
`drafts/outreach-*.csv`	`raven draft`	Send-ready spreadsheet

npm scripts #

Equivalent to ./raven subcommands:

Filters

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

Discovery filters #

Filters apply during raven discover, raven scan-ats, raven scan-boards, and raven query.

CLI flags #

Flag	Description	Example
`--q "keywords"`	Title must match (comma-separated)	`--q "backend, engineer"`
`--not "words"`	Title must not contain	`--not "nurse, sales"`
`--loc Remote,EU`	Location allow-list	`--loc Remote,India`
`--noloc "On-site"`	Location block-list	`--noloc "San Francisco"`
`--since N`	Posted within last N days	`--since 7`
`--ats greenhouse,lever`	Limit ATS platforms	`--ats ashby,workday`
`--max N`	Cap total results	`--max 100`
`--limit N`	Per-provider limit	`--limit 50`

Config vs CLI #

When CLI flags are omitted, Raven merges filters from config/portals.yml:

JD tailoring

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

Job description tailoring #

For each job, Raven extracts keywords from the title and matches your resume bullets to produce tailored application content.

Output columns #

Column	Meaning
`jd_keywords`	Terms extracted from job title (e.g. `backend`, `python`, `remote`)
`action_words`	Suggested verbs for this role type
`tailored_bullets`	Top resume bullets ranked by relevance to the JD

How matching works #

Keyword extraction — splits title on common separators, filters stop words
Bullet scoring — each resume bullet scored by keyword overlap with title
Action words — role-type heuristics (backend → “architected”, “scaled”; ML → “trained”, “deployed”)
Top N — resume.max_bullets from profile (default 5)

Example #

Job title: Senior Backend Engineer — Node.js

Pipeline

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

Discover → Draft → Send #

Raven’s workflow is three stages. Each stage produces artifacts the next stage consumes.

Stage 1: Discover #

raven discover

Input: config/portals.yml filters (+ optional CLI flags)

Output: data/jobs.json (auto-saved)

Sources (parallel):

Tier	Flag	Description
ATS	`--sources ats`	Live APIs: Greenhouse, Lever, Ashby, Workday, …
Boards	`--sources boards`	RemoteOK, Remotive, Arbeitnow, Landing.jobs
Index	`--sources index`	Local SQLite from openjobdata
hiring.cafe	`--sources hiringcafe`	Opt-in; may need `HIRING_CAFE_ENABLED=1`

Stage 2: Draft #

raven draft --max 25

Input: data/jobs.json + config/profile.yml + parsed resume

profile.yml

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

profile.yml #

config/profile.yml is the source of truth for who you are when Raven drafts applications.

Structure #

identity:
 name: "Your Name"
 email: "you@example.com"
 phone: ""
 location: "City, Country"

links:
 resume: "files/resume.md"
 portfolio: "https://yoursite.dev"
 github: "https://github.com/yourhandle"
 linkedin: "https://linkedin.com/in/yourhandle"
 x: "https://x.com/yourhandle"

highlights: [] # optional manual overrides
skills: [] # optional manual overrides

resume:
 path: "files/resume.md"
 max_bullets: 5

draft:
 gemini:
 enabled: false
 model: "gemini-2.0-flash"
 disclaimer: "Review and edit this draft yourself before sending or submitting."

outreach:
 greeting_generic: "Hey team"
 subject: "Application: {{title}} at {{company}}"
 body: |
 {{greeting}},

 I'm writing about the {{title}} role at {{company}}.

 {{highlights}}

 Best,
 {{senderName}}

Template variables #

Used in outreach.subject and outreach.body:

Quick Start

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

Quick Start #

Five minutes from zero to your first tailored application drafts.

1. Setup #

cd raven
./raven setup

2. Configure filters and profile #

Edit config/portals.yml — what jobs to find:

title_filter:
 positive:
 - "software engineer"
 - "backend"
 - "developer"
 negative:
 - "nurse"
 - "sales"

location_filter:
 allow:
 - "Remote"
 - "India"

Edit config/profile.yml — who you are when drafting:

identity:
 name: "Your Name"
 email: "you@example.com"
 location: "City, Country"

links:
 resume: "files/resume.md"
 portfolio: "https://yoursite.dev"
 github: "https://github.com/you"
 linkedin: "https://linkedin.com/in/you"

Replace files/resume.md with your real resume (Markdown with ## Experience and - bullets works best).

ATS form guides

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

ATS form guides #

When a job’s apply URL points to an ATS (Greenhouse, Lever, Ashby, Workday, etc.), Raven generates a form application guide instead of an email.

Application types #

Type	Detected when	Raven output
`email`	Direct email outreach possible	Subject + body
`form`	Apply URL on known ATS domain	Step-by-step `form_steps`

Form rows are not sent via raven send. Open the markdown review or CSV form_steps column and follow the guide in your browser.

Environment variables

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

.env reference #

Copy from .env.example on raven setup. Secrets stay local — never commit .env.

Sender identity #

SENDER_NAME=Your Name
SENDER_EMAIL=you@example.com

Used by raven send and draft disclaimers.

Gmail OAuth #

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GMAIL_REFRESH_TOKEN= # populated by raven auth-gmail

Create OAuth credentials in Google Cloud Console with Gmail send scope.

Outlook OAuth #

MS_CLIENT_ID=
MS_CLIENT_SECRET=
MS_REFRESH_TOKEN= # populated by raven auth-outlook

Example Dry Run

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

Example Dry Run #

Complete pipeline walkthrough without sending email. Copy commands from your Raven repo root.

Step 0 — Install #

cd raven
./raven setup

Step 1 — Configure #

config/profile.yml — name, email, portfolio, GitHub, LinkedIn, resume path
files/resume.md — your resume with - bullets under ## Experience
config/portals.yml — title keywords (e.g. software engineer, backend, developer)

No Gmail OAuth needed for this dry run.

openjobdata

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

openjobdata index #

Raven syncs the openjobdata dataset into a local SQLite database for fast offline search.

Sync #

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

What happens #

Downloads companies registry from HuggingFace bucket Invicto69/Jobs-Dataset-bucket
Fetches recent daily parquet deltas
Upserts into data/jobs.db
Exports ATS company slug lists to data/cache/ats-companies/

Authentication #

If sync returns HTTP 401:

# .env
HF_TOKEN=hf_xxxxxxxx

Create a read token at huggingface.co/settings/tokens.

Query local index #

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

Same filter flags as discover: --q, --not, --loc, --since, --ats, --max.

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.

Troubleshooting

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

Troubleshooting #

Common issues and fixes.

`raven: command not found` #

# From repo root
./raven --help

# Or install globally
npm link
raven --help

If npm link resolves to the wrong path, use ./raven from the repo root.

`raven draft` — no input file #

Discover auto-saves to data/jobs.json. Run discover first:

raven discover --q "engineer"
raven draft --max 25

Or pass explicit input:

raven draft --input data/jobs.json

Unrelated jobs (nurse, sales, etc.) #

Bare raven discover reads config/portals.yml. Fix filters:

Gemini plugin

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

Gemini draft plugin #

Optional AI polish for email drafts via Google’s Gemini API.

Setup #

Get an API key from Google AI Studio
Add to .env:

GEMINI_API_KEY=your_key_here

Enable in profile (optional):

draft:
 gemini:
 enabled: true
 model: "gemini-2.0-flash"

Usage #

raven draft --input data/jobs.json --gemini --max 10

Or one-shot discover + draft:

raven draft --q "backend engineer" --gemini --max 5

What Gemini does #

Rewrites email subject and body for clarity and tone
Preserves factual content from your resume bullets
Does not fabricate experience — works from parsed resume + JD keywords

What Gemini does not do #

Form application guides (ATS rows stay template-based)
Verify email addresses
Auto-send — you must review and run raven send yourself

Disclaimer #

Every draft includes:

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.

Raven

How discovery works

How job discovery works #

TL;DR #

What “search” means #

setup

raven setup #

Architecture

Architecture #

Layers #

CLI layer (bin/raven, scripts/) #

Discovery engine (jobs/) #

Providers (jobs/providers/) #

discover

raven discover #

Usage #

Behavior #

Flags #

Output JSON shape #

Tips #

Installation

Installation #

Requirements #

Clone and setup #

Install raven globally (optional) #

Logging

Logging #

Default behavior #

Flags #

Commands with logging #

Log contents #

portals.yml

portals.yml #

How discover uses it #

Minimal example #

Title filter semantics #

Location filter semantics #

Resume parsing

Resume parsing #

Supported formats #

Markdown structure #

Parsing rules #

Cache #

Sources & tiers

Job sources #

Tier 1 — Live ATS APIs (--sources ats) #

Workflow

Outreach workflow #

1. Discover #

2. Draft #

3. Review #

Scan strategies

Scan strategies #

Four levels (from portals.example.yml) #

draft

raven draft #

Usage #

Input sources #

Output files #

CSV columns #

Flags #

Application types #

Form (application_type: form) #

File layout

Repository layout #

Tracked vs gitignored #

Key data files #

npm scripts #

Filters

Discovery filters #

CLI flags #

Config vs CLI #

JD tailoring

Job description tailoring #

Output columns #

How matching works #

Example #

Pipeline

Discover → Draft → Send #

Stage 1: Discover #

CLI layer (`bin/raven`, `scripts/`) #

Discovery engine (`jobs/`) #

Providers (`jobs/providers/`) #

Install `raven` globally (optional) #

Tier 1 — Live ATS APIs (`--sources ats`) #

Form (`application_type: form`) #

`raven: command not found` #

`raven draft` — no input file #