CLI

OpenOpps exposes the openopps console script from openopps.cli:app. Treat the CLI as a local data pipeline: source catalogs become durable board records, board records become executable provider routes, provider routes become normalized jobs, and exports preserve the resulting ledger for audit or analysis.

Invocation

Run through the repository environment during development:

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

Install the current checkout as an editable uv tool when you want to call openopps directly:

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

The editable tool uses the same runtime settings as uv run, including OPENOPPS_DB_URL, plugin allow lists, cache settings, and current working-directory-relative SQLite paths.

Workflow

The normal sequence is:

1. Run sync for source discovery, board route resolution, and job sync in order.
2. Use sources sync, boards sync, or jobs sync when rerunning one stage.
3. Inspect providers coverage, providers audit, or admin providers registry when route metadata is incomplete.
4. Use jobs list, boards export, or jobs export for analysis.

Use status or doctor between steps to see counts, route readiness, cache state, plugin load state, and the next recommended action.

Safety Classes

--apply is intentionally absent from most everyday commands. When it appears on diagnostics such as route probing or health checks, treat it as the boundary between inspection and persistence.

Command Groups

Option Conventions

Examples use long flags for readability. The CLI also exposes script-friendly short aliases for high-traffic options:

--provider any and --provider all both remove the provider filter. They are useful in reusable scripts that always pass a provider argument, but they do not mean “only providers named any/all.”

Common Commands

uv run openopps status --json
uv run openopps doctor --json
uv run openopps sync a16z --metrics-json --refresh-cache
uv run openopps sources sync a16z --metrics-json
uv run openopps boards sync --source a16z --provider any --metrics-json
uv run openopps jobs sync --provider ashbyhq --metrics-json --refresh-cache
uv run openopps providers coverage --source a16z --provider any --json
uv run openopps admin providers probe-routes --source a16z --provider any --limit 25 --json

Provider hints from source catalogs may lack 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. It is read-only unless --apply is passed.

Board Filters

boards list and boards export share these filters:

Use the exact persisted board key shown by boards list; provider requests are deduped before probing or job sync when overlapping source coverage points at the same provider route.

Job Filters

jobs list and jobs export default to current active jobs with --status open across all boards and providers. Use --status closed or --status all for lifecycle audits.

Date filters intentionally only match jobs whose normalized posted_at starts with YYYY-MM-DD, such as ISO timestamps. Relative provider text such as Posted Yesterday is not used for public filtering semantics.

Exports

uv run openopps boards export --provider ashbyhq --has-jobs --format csv --output /tmp/openopps-boards.csv
uv run openopps jobs export --source a16z --type full --format parquet --output /tmp/openopps-jobs.parquet

boards export and jobs export support:

JSONL exports stream line-delimited records and empty JSONL/CSV exports produce empty files. Empty Parquet exports produce a readable empty Parquet table. CSV exports neutralize spreadsheet formula-leading strings by prefixing a single quote. SQLite exports should keep the same flattened field contract as CSV/Parquet and store nested values as stable JSON strings.

For schema, SQLite, and search-index details, see Data Model.

Troubleshooting Map