Start Here

OpenOpps v0.1 is a Python CLI for discovering firm hiring boards from aggregate sources, detecting public provider routes, syncing normalized jobs, caching repeated HTTP JSON requests, and exporting an auditable local opportunity ledger. Ingestion and durable state are CLI-driven; the published Jobs and Explorer surfaces are a static docs workbench over a committed search snapshot, not a hosted sync service. There is no prompt UI or TUI.

Browse the committed snapshot

Use the

Jobs

surface for open-role search and posting previews, or

Explorer

for source, provider, route, and data-quality analysis.

DiscoverRead source catalogs and persist durable board records.

ResolvePromote provider hints into executable public job routes.

ExportWrite normalized boards and jobs as JSONL, CSV, Parquet, or SQLite.

Domain

sources are aggregate discovery catalogs such as a16z, accel, lsvp, sequoia, bvp, greylock, kleinerperkins, southparkcommons, signalfire, and yc.
boards are firm/company hiring boards discovered from sources.
jobs are normalized postings fetched from boards.
providers are adapters that detect or fetch provider-specific boards, such as Ashby, Greenhouse, Lever, Workday, Workable, Teamtailor, BambooHR, Rippling, and WP Job Manager.
cache, plugins, and examples cover operational cache inspection, installed Python plugin discovery, and deterministic demo data.

Install and Run

Use uv run while working inside the repository checkout:

uv sync
just --list
uv run openopps --help
uv run openopps status

If you want openopps available directly from this editable checkout, install the repo as a uv tool from the repository root:

uv tool install -e .
openopps --help
openopps status

uv tool install -e . installs the console entry point from the current checkout. Runtime settings such as OPENOPPS_DB_URL still control where local SQLite state is read and written.

First run

Before live syncs against public upstreams, initialize the durable SQLite schema for the database you intend to use:

uv run openopps admin db init
uv run openopps admin db status

OPENOPPS_DB_URL defaults to sqlite:///openoppsdb.sqlite relative to the process working directory. For an isolated smoke database, point at a dedicated file before admin db init and sync:

OPENOPPS_DB_URL=sqlite:///./tmp/openopps-smoke.sqlite uv run openopps admin db init
OPENOPPS_DB_URL=sqlite:///./tmp/openopps-smoke.sqlite uv run openopps examples seed --json

See Configuration for concurrency and job-route settings.

Contributor Command Map

The root Justfile is the quickest way to discover local validation without hiding the underlying toolchain:

just --list
just quick
just ci
just openspec-validate-all
just web-check
just cli-help

just ci composes the ci-python, ci-openspec, ci-web, and ci-artifacts lanes. Those cover the Python release gate, strict OpenSpec validation, web type/build/unit/browser/accessibility/lint/search-artifact checks, Kaggle metadata/bundle smoke, and repository drift. Use the raw uv, pnpm, and OpenSpec commands from the reference pages when a CI failure needs exact reproduction; use just ci-full when network-dependent security audits and lowest-direct dependency tests are required.

Safe Local Smoke Path

These commands seed deterministic demo records and do not hit upstream source or provider services:

uv run openopps examples seed --seed 42 --boards 4 --jobs-per-board 2 --json
uv run openopps jobs list --source example --json
uv run openopps providers coverage --json

Live Quickstart

The commands below read public upstream catalogs and provider endpoints. They write local SQLite state unless a command is explicitly marked no-DB or dry-run.

uv run openopps sources list
uv run openopps admin sources test a16z
uv run openopps sources sync a16z --metrics-json --refresh-cache
uv run openopps sources sync accel --metrics-json
uv run openopps sources sync greylock --metrics-json
uv run openopps boards list --source a16z --limit 10
uv run openopps admin boards enrich --source a16z --json
uv run openopps providers health --source a16z --provider any --limit 25 --json
uv run openopps admin providers probe-routes --source a16z --provider any --limit 25 --json
uv run openopps jobs sync --provider ashbyhq --metrics-json --refresh-cache
uv run openopps cache status --json
uv run openopps plugins list --json

Unscoped list, export, and sync commands use the full known superset unless narrowed by --source, --board, or --provider. Provider filters accept any and all as aliases for removing the provider filter, which keeps reusable scripts explicit without narrowing to one provider.

Overlapping source coverage uses the persisted board keys shown by boards list, and provider requests are deduped before route probing or job sync. The relevant metrics include duplicateRoutesSkipped.

Provider Levels

Level	Meaning
`detect`	OpenOpps can preserve provider metadata and route hints.
`jobs`	OpenOpps can fetch public jobs for the provider.
`unsupported`	The provider is known only as raw metadata.

Ashby, Greenhouse, Lever, public Workday CXS, Workable, Teamtailor, BambooHR, Rippling, and explicit WP Job Manager boards are job-capable in v0.1 through public no-auth routes. Manatal and Gem hints remain detect-only until stable public fetching is added. See Providers for the generated provider registry and route diagnostics.

Ashby postings marked isListed: false are direct-link-only and are excluded from normal job sync output.

Documentation Map

Page	Use it for
CLI	Command groups, common flags, JSON output, filters, and exports.
Configuration	`OPENOPPS_` environment variables, defaults, `.env` loading, and runtime policy.
Data Model	Sources, boards, providers, jobs, exports, static indices, counts, and telemetry event-lake guidance.
Providers	Source catalogs, provider support levels, route diagnostics, and limitations.
Operations	Storage, cache, exports, validation, telemetry operations, Kaggle, and troubleshooting workflows.
Public Data Releases	V7 manifests, source-rights gates, release-pinned web reads, static delivery, rollback, recovery, and the v6 cutover boundary.
Contributing	Local setup, validation, docs generation, source-batch rules, and review expectations.
Jobs	Filter and preview open roles from the static search index.
Explorer	Analyze source/provider coverage, route health, freshness, and data quality.

Public Docs Routes

The canonical jobs workbench is /, the canonical analytics explorer is /explorer, and thin job detail pages live at /jobs/:id for direct posting previews. Legacy /jobs redirects to /, and legacy /docs/explorer redirects to /explorer; do not add broad /jobs/:path redirects because detail pages must remain addressable.

LLM-readable docs

The docs app exposes machine-readable exports for agents and tooling:

URL	Purpose
`/llms.txt`	Compact index of documentation pages for LLM context.
`/llms-full.txt`	Full concatenated docs text for deeper retrieval.

Per-page markdown routes are also available under /llms.mdx/ when you need a single MDX page in isolation.

Route Probing Summary

Provider hints from source catalogs may not include the token or URL needed for job fetching. admin providers probe-routes tries candidate tokens from upstream slugs, remote ids, names, domains, and websites, then reports both matched routes and unknown boards with the candidate tokens it tried. Its JSON output includes per-provider selected/matched counts, unresolved reason counts, and duplicate route skips.

uv run openopps admin providers probe-routes --source a16z --provider all --limit 25 --json

Probing is read-only unless --apply is passed. Use CLI for command flags and Operations for local-state runbooks.

Start Here

On this page