Configuration #

Raven reads YAML from config/ and secrets from .env. User-specific files are gitignored — templates ship as *.example.yml.

Run raven setup once to copy all examples into place.

Pages in this section #

portals.yml

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:

1. Raven loads config/portals.yml (or path from RAVEN_PORTALS in .env)
2. Title keywords from title_filter.positive become --q filters
3. Negative keywords become --not filters
4. 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:

profile.yml

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:

Environment variables

.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

Register an app in Azure Portal with Mail.Send permission.

Config files overview #

What to edit first #

1. profile.yml — your name, email, portfolio, GitHub, LinkedIn
2. files/resume.md — replace the example with your real resume
3. portals.yml — title_filter.positive keywords for roles you want
4. .env — only needed when you are ready to send email

./raven setup          # creates all config from examples
./raven discover       # uses portals.yml filters
./raven draft --max 5  # uses profile.yml + resume

Start with portals.yml →