freehire-search skill

freehire Search Skill

Search live job listings from the freehire.me job aggregator — an open-source IT job board that normalizes postings from ~50 ATS platforms across many countries into one schema. No authentication, no API key, and zero runtime dependencies — it runs with just bun. The market is chosen per query via facet flags (--region, --country), so the same skill works for a forker in any market out of the box.

This is a country-agnostic worked example of the repo's job-portal-skill pattern,

like linkedin-search. Unlike the HTML-scraping portals, it queries freehire's

public JSON API, so results are structured (skills, seniority, region facets)

rather than parsed from markup.

⚠️ Scope: tech-focused

freehire's corpus already includes some non-tech postings (it crawls whole company career pages), but its faceted filtering — skills, categories, and seniority dictionaries — is tuned tech-first today, so this skill scopes its triggers to software / data / engineering / tech roles, where the filtering is strong. Non-tech coverage exists but is still maturing; don't rely on this skill for general (non-technical) job coverage yet.

ℹ️ Hosted-service dependency (best-effort, no SLA)

This skill depends on a third-party hosted service, freehire.me. Reads are public and unauthenticated — the same zero-signup bar as linkedin-search.

freehire.me is a personal project but actively maintained; it runs on a best-effort basis (no formal SLA). If the API is unreachable, the CLI fails gracefully — a non-zero exit with a clear error message — so an outage degrades this source rather than breaking the surrounding workflow.

Self-hosting / swappable base URL. The freehire backend is a separate MIT-licensed repo — strelov1/freehire (Go + PostgreSQL + Meilisearch) — that stands up with one command via Docker Compose (make up → API on :8080, same /api/v1/... paths). The skill honors a base-URL env var, FREEHIREAPIURL (default https://freehire.me), so pointing it at a local instance is a one-line change:

FREEHIRE_API_URL=http://localhost:8080 bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "go"

Caveat: standing up the API is light, but keeping a full, continuously-fresh mirror (millions of postings across ~50 platforms) is resource-heavy — a self-hoster would either crawl a scoped subset of sources or point the env var back at the hosted API.

When to use this skill

each result comes back with its full description, no per-hit follow-up needed

• Search for tech job openings by keyword, in a given region/country or remotely —

• Filter by seniority, category, skills, or recency (posted within N days)
• Look one freehire posting up by its slug (including a closed one)

Commands

Search job listings

bun run .agents/skills/freehire-search/cli/src/cli.ts search [-q "<keywords>"] [facet flags]

Query syntax: quotes require every quoted word (any order, not a contiguous phrase); -word excludes; uppercase OR between terms matches any alternative (max 5, merged and deduplicated server-side); title: at the start of an alternative matches it in the title only, e.g. title:"product owner" -junior OR title:produktchef.

Key flags:

Supports OR and title: (see "Query operators" below).

• --query / -q — keyword search (title, skill, role). Full-text; optional.

rendered. Default markdown, which keeps the posting's headings and requirement lists intact. json output only.

• --jobage — posted within N days (maps to postedwithindays).
• --page — 1-indexed page. Default 1.
• --limit / -n — results per page (API limit). Default 25.
• --format json|table|plain — default json.
• --description-format markdown|text|html — how each result's full description is

Query operators. -q understands two operators; the CLI passes the text through unchanged and the API parses it:

-q "golang OR rust". Uppercase only: a lowercase or is an ordinary search word. Plain space-separated words are not a union (-q "golang rust" returns fewer jobs than -q golang alone), so use OR for synonyms and alternative stacks instead of running one search per keyword. At most 5 alternatives; a 6th is rejected with an error. An OR inside double quotes is literal text.

• OR between alternatives returns jobs matching any of them, e.g.

-q "title:staff engineer" skips postings that merely mention the words in their description. It applies per alternative, so repeat it on each one: -q "title:staff engineer OR title:principal engineer". It only counts at the start of an alternative; title: in the middle is searched as text. Quotes work inside it: -q 'title:"staff engineer"' matches the phrase.

• A leading title: restricts that alternative to the job title, e.g.

Facet flags, --jobage, --page and --limit apply to the combined result: every alternative is filtered the same way, and a job matching several alternatives appears once.

Search results already carry the full description. This skill queries freehire's agent search endpoint, which replaces the index's truncated preview with each posting's complete text, so a search of 20 roles is 1 request rather than 1 + 20. Do not loop detail over search hits to read their descriptions — reach for detail only to look one posting up by slug (e.g. from the tracker, or a posting already closed and therefore absent from search). Full descriptions are verbose: keep --limit modest, and pre-filter on title/company before reading bodies - or pass --no-description for a cheap discovery pass that keeps every other field and drops the bodies entirely (fetch a shortlisted job's body with detail, or re-run the search without the flag).

Facet filters (values come from freehire's controlled vocabularies; comma-separate for OR within a facet):

• --region - macro-region: global, eu, uk, northamerica, latam, apac, mena, africa, cis. --region eu,uk. eu does not include the UK; add uk for Europe as a whole. For a single country use --country instead - us is a country code, not a region, and --region us matches nothing. --region, --country and --city form one OR-group, so --country us alone scopes to the US. Use none to match jobs whose region could not** be resolved (see "Partial data" below).
• --country — ISO-3166 alpha-2, e.g. --country DE,GB
• --city — city name(s), e.g. --city Berlin
• --seniority — junior, middle, senior, staff, principal, lead, …
• --category — backend, frontend, fullstack, devops, ml_ai, qa, …
• --skill — canonical skill(s), e.g. --skill go,kubernetes
• --company — company slug (from a result's company_slug)
• --remote — remote | hybrid | onsite (workmode facet). A bare --remote means remote. Comma-separate for OR (remote,hybrid; on-site normalises to onsite). An unknown item exits 1 with BADARG.
• --facet — any other facet param (repeatable), e.g. --facet salary_min=100000

Location is a facet, not free text. Unlike linkedin-search's --location,

freehire filters geography through the structured --region/--country/--city

facets. Discover the live values for a market at

/api/v1/jobs/facets (append ?q=

to scope it) — never invent facet values.

Fetch full job detail

bun run .agents/skills/freehire-search/cli/src/cli.ts detail <slug|url> [--format json|plain]

slug is the id from a search result (e.g. golang-zensar-2bxu6dxm). You may also pass a full https://freehire.me/jobs/ URL. A URL on any other host - including the employer apply link a search result's url field carries - is rejected with BAD_ID before any request. Returns the full (HTML-stripped) description, skills, region/country, and — when the posting is enriched — seniority, category, employment type, and salary. salary keeps its period when freehire records one (INR 300000–300000/year, INR 12000/month); compare pay only in one period.

Use it for a posting you already have a slug for — a tracked application, a shared link, or a closed posting search no longer lists. Re-fetching a hit that search just returned only re-reads a description you already have.

Usage examples

# Senior backend roles, table view
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "backend engineer" --seniority senior --limit 10 --format table

# Go or Rust roles, one search (OR must be uppercase)
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "golang OR rust" --remote remote --format table

# Staff or principal titles only, not postings that mention them in passing
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "title:staff engineer OR title:principal engineer" --format table

# Remote React roles in the EU
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "react" --remote remote --region eu --format table

# DevOps roles in Germany posted in the last 14 days
bun run .agents/skills/freehire-search/cli/src/cli.ts search --category devops --country DE --jobage 14 --format table

# ML/AI roles anywhere, fully remote
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "machine learning" --category ml_ai --remote remote --format table

# Descriptions as plain text instead of Markdown
bun run .agents/skills/freehire-search/cli/src/cli.ts search -q "platform engineer" --limit 5 --description-format text

# F

Output formats

Search JSON is { "meta": { "count", "page", "total" }, "results": [...] }; each result carries at least id (the freehire slug), title, company, location, date, url, and description (missing values are null). table and plain omit the description — it would swamp a scannable list. All errors are written to stderr as { "error": "...", "code": "..." } and the process exits with code 1.

One diagnostic is not an error: a --region (or --facet regions=) value outside the documented vocabulary - us is a country code, not a region - prints { "warning": "...", "code": "REGIONVALUEUNKNOWN" } on stderr after the results, and the process still exits 0 with stdout a valid JSON document.

Partial data

Facets are derived per-posting and can be incomplete — geography especially. A job may resolve its workmode (e.g. remote) but leave its region or country undetermined** when the source's location text is ambiguous (freehire's dictionaries never guess). So:

filtering on --region eu silently drops jobs whose region wasn't resolved, even if they are in fact EU. Widen or drop the facet if you need those back.

• A missing region/country means "not resolved", not "not applicable" —

matches jobs with no resolved region — useful to sweep up remote roles that never pinned a geography. It ORs with real regions, e.g. --region eu,none.

• There is a dedicated facet value for the unresolved bucket: --region none

reason; treat empty as unknown, not as "none of the above".

• result.regions / countries / cities may be empty arrays for the same

Notes

tracking (apply/save) needs a key, and this skill deliberately does not touch it: it is search + detail only.