stage-cli 1.1.0

  ____  _
 / ___|| |_   __ _   __ _   ___
 \___ \| __| / _` | / _` | / _ \
  ___) | |_ | (_| || (_| ||  __/
 |____/ \__| \__,_| \__, | \___|
                    |___/

Why

Internships disappear fast. By the time you find the right posting, hundreds of students may already be ahead of you. Most job boards make it worse by burying relevant roles under senior positions, research jobs, and listings nowhere near you.

Stage scans 1,450+ employer career boards and finds internships CS undergrads in Canada and the U.S. can actually apply to. Every rejected posting is logged with the exact reason it was filtered out.

It has kept 4,165 postings out of 138,533 screened so far.

A look at it

_{stage tui — browse everything, filter with f, open with o}

_{stage --help — commands grouped by what you are doing}

Install

uv tool install stage-cli

pip install uv

pipx install stage-cli                  # isolates the tool, like uv
pip install stage-cli                   # installs into the active environment

Needs Python 3.12, 3.13, or 3.14. Nothing else to set up — no database to configure, no API key, no config file.

First run

stage sync                    # fetch every board once (grab a coffee)
stage tui                     # browse what came back

The first sync visits every board and takes a few minutes. Later ones are much quicker, since Stage remembers what it already has and only asks each board for what changed.

stage --install-completion    # tab-complete commands and filters

Completion needs a fresh terminal. After that, stage <TAB> lists commands and stage list --<TAB> lists filters.

The basics

stage sync                            # fetch the latest postings
stage list                            # what is new, newest first
stage search "machine learning"       # search titles, employers, descriptions
stage tui                             # browse it all in a full screen

Rows are numbered, so you can act on what you just saw:

stage list --role swe --location montreal
stage show 3                          # read the third row in full
stage open 3 5 9                      # open those three in your browser

Filters work the same on list, search, and export:

Mistype one and Stage tells you what it accepts, rather than showing you an empty list.

The full-screen browser

stage tui

Press / to search and f for filters — arrows move, enter picks, escape closes. Role, location, language, how far back to look, new-since-last-sync and the employer you are sitting on all live in that one panel. space marks rows and o opens every one you marked. w expands the full description, e exports what you are looking at, and ctrl+t changes the theme. Press ? for the full key list.

Same database as the CLI. The panel covers role, location, language, the date window and new-since-last-sync; --term and --source stay CLI-only. Row numbers are a CLI idea — in the TUI you move a cursor instead.

Keeping it fresh

stage schedule enable     # sync quietly in the background
stage schedule status     # check on it

Opt-in, and it uses whatever scheduler your system already has: launchd, systemd, or Task Scheduler. Nothing runs until you turn it on.

Want to hear about new postings without checking? Point Stage at a Discord channel you manage:

stage schedule notify https://discord.com/api/webhooks/...
stage schedule test-notify        # make sure it works

Create a Discord webhook in the channel you want Stage to post to. It is just a URL Stage uses to send new internships.

Notifications only follow scheduled syncs, not stage sync. Your machine also needs to be awake. If it misses runs, Stage catches up once when it can run again.

uv tool install stage-cli
stage sync                         # first sync, a few minutes
stage schedule notify <webhook>
stage schedule enable              # systemd, launchd, or Task Scheduler

Architecture

Stage/
├─ src/stage/
│  ├─ cli/                  Typer commands, Rich rendering, scheduling, notify
│  ├─ tui/                  Textual screens over the same services; safe.py escapes output
│  ├─ domain/               the types every layer speaks: jobs, filters, enums, events
│  ├─ sources/              13 ATS adapters + 11 curated feeds
│  ├─ services/             sync, discover, query, export, quarantine, health
│  ├─ classify/             role, internship scope, degree eligibility, location
│  ├─ normalize/            location, term, language, apply-url canonicalisation
│  ├─ dedup/                cross-source duplicate resolution
│  ├─ http/                 rate posture, circuit breaker, validator cache
│  ├─ storage/              SQLite repository, migrations, FTS
│  └─ data/                 packaged registry (a directory) and lexicons
├─ tests/                   2,381 tests, 89% branch coverage
└─ .github/workflows/       CI, CodeQL, scheduled canary, release

┌──────────────────────────────────────────────────────────────┐
│                    1,450+ employer boards                    │
│    Greenhouse · Lever · Ashby · Workday · SmartRecruiters    │
│                + 11 curated internship feeds                 │
└───────────────────────────┬──────────────────────────────────┘
                            │  rate-limited, cached, backed off
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                          normalize                           │
│       location · term · language · canonical apply URL       │
└───────────────────────────┬──────────────────────────────────┘
                            ▼
┌──────────────────────────────────────────────────────────────┐
│                            screen                            │
│    internship? · CS role? · degree scope? · Canada or US?    │
│        every rejection keeps the rule that caught it         │
└──────────────┬───────────────────────────────┬───────────────┘
               │ kept                          │ rejected
               ▼                               ▼
        ┌─────────────┐                 ┌─────────────┐
        │    jobs     │                 │ quarantine  │
        │    4,165    │                 │   134,368   │
        └──────┬──────┘                 └─────────────┘
               │  dedup collapses the same posting across sources
               ▼
     ┌───────────────────────┐
     │     SQLite + FTS5     │
     │    on your machine    │
     └──────┬────────┬───────┘
            ▼        ▼
      stage list   stage tui
      search       full-screen browser
      export       Discord on a schedule

CI

Any failing gate blocks the merge. The canary runs weekly and opens an issue when a board changes shape, so parser drift surfaces before a sync does.

Every run also builds the wheel and installs it into a clean environment outside the checkout on Ubuntu, Windows and macOS, checks the registry, lexicons and font resolve from inside the installed package, then runs help, list, search, doctor, coverage, stats, a dry-run sync and all four export formats against it. What ships is what gets tested.

Good to know

• Everything sits in one SQLite file you own. Open it with any SQLite client, back it up, or delete it.
• The only network traffic is Stage reading public job boards. No account, no telemetry.
• Requests are rate limited per host, cached, and retried with backoff, so it does not hammer anyone's site.
• Four in five postings arrive with no description at all. Stage marks those fields unknown instead of guessing.
• Missing something you expected? stage quarantine shows which rule caught it.

Learn more

stage help walks through the common workflows with real examples. stage help COMMAND explains one command; stage --help lists them all.

CHANGELOG.md lists what changed in each release.

Found a bug?

Open an issue, especially if a job board stopped working, since those break without warning and I cannot watch all of them myself. I read everything.

Security

Stage reads public job boards and writes to a local file. It never asks for credentials. Found a security issue? Open a security advisory instead of a public issue.

License

MIT. See LICENSE.