freehire-job-search
Use when finding jobs for someone — searching or filtering the freehire catalogue by keyword, region, seniority, skills, salary or company; reading a posting or a company's open roles; discovering what values a filter accepts; reading the saved job-search profile before asking someone what they want; handing over a job link freehire does not carry yet; or reading the "possibly inactive" signal on a posting. Covers profile, facets, search, job, company and contribute, all with machine-readable `--json` output.
strelov1 · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add strelov1/freehire-cli --skill freehire-job-searchAbout this skill
name: freehire-job-search
description: Use when finding jobs for someone — searching or filtering the freehire catalogue by keyword, region, seniority, skills, salary or company; reading a posting or a company's open roles; discovering what values a filter accepts; reading the saved job-search profile before asking someone what they want; handing over a job link freehire does not carry yet; or reading the "possibly inactive" signal on a posting. Covers profile, facets, search, job, company and contribute, all with machine-readable --json output.
Finding jobs on freehire
freehire is a single static binary over the freehire.me
job API. It searches, filters and opens jobs without a browser. Every command
supports --json for a raw, faithful API payload (pipe to jq).
Needs a key: freehire auth login --token fhk_… (or FREEHIRE_TOKEN). A 401
means "run freehire auth login".
The loop
0. Read the person's own profile before asking them anything.
freehire profile # roles, skills, skills to avoid, geography, CV
freehire --json profile | jq '.skills, .cv.total_years'
They have already told freehire which roles and skills they want, which they
would rather avoid, and where and how they will work. Start from that and say what
you searched on; ask only about what it does not answer. It returns null data when
they have saved none — then point them at https://freehire.me/my/profile rather
than collecting the same answers in the conversation, because what they save there
also drives their recommendations and alerts. Contact details are never included.
1. Discover what you can filter by — before guessing values.
freehire facets # every filter's live values + counts, and skills
freehire facets --category backend # values relevant to a slice (e.g. backend skills)
freehire --json facets | jq '.facets.skills' # canonical skill slugs with demand
facets is the vocabulary source of truth: it returns each facet's valid values
(category, seniority, regions, countries, role, skills, english_level,
…) with a vacancy count each, plus numeric ranges (salary_min, …). Read it first
so search filters use real values and skills use canonical slugs. Skills are
lowercase slugs (go, react, kubernetes) — do not invent facet values.
2. Search with keyword + facet filters.
freehire search "golang" --remote --region eu --seniority senior
freehire search "data" --country BR --employment-type full_time
freehire search "AI" --country IT --employment-type contract --exclude-skill python
freehire search "backend" --facet source=greenhouse # any facet via --facet key=value
freehire search "keep our payment systems secure" --semantic # match by meaning, not only words
Query syntax. The keyword argument is more than a bag of words:
| Write | Means |
|---|---|
"product owner" | every quoted word must match, in any order (not a contiguous phrase) |
-junior | exclude postings that match it |
produktchef OR "product owner" | any alternative matches; uppercase OR, at most 5 alternatives, merged and deduplicated server-side |
title:"product owner" | at the start of an alternative: match it in the title only, so a posting that merely mentions the role in its body is left out |
freehire search 'title:"product owner" -junior OR title:produktchef'
freehire search 'golang OR rust' --remote
- Single-quote the whole query whenever it has double quotes. The shell
strips unprotected quotes:
freehire search title:"product owner"sendstitle:product ownerand matched 59,406 postings instead of 6,028. - Prefer one
ORcall to one call per synonym. Paging, the total and the counts already describe the merged set. - Plain words are neither AND nor OR. The first ones are required and trailing ones are dropped when too few match, so word order changes the result. Quote the words that must all appear.
--semanticwhen the need is described rather than named. "keep our payment systems secure" has no job title in it; with--semanticit also reaches postings that say the same thing in other words. Leave it off for a job title ("react developer") or a non-technical role ("nurse night shift"): there it measurably does worse than plain keywords, because only technical postings carry the vectors it matches on. A stderr warningsemantic search unavailablemeans the results are keyword-only.
Repeatable filter flags (pass again to OR more values): --region --country --city --company --category --role --seniority --employment-type --english-level --exclude-skill --skills --facet. Single-valued: --remote and --visa are
toggles, --salary-min is one number. --facet key=value reaches any other facet
in the vocabulary. --skills here is a filter (jobs listing the skill).
--limit/--offset page.
Filtering things OUT. --exclude-skill python drops jobs tagged with that
skill — the way to say "contract work, but not the Python ones". Every other
facet takes the same _exclude suffix through --facet, e.g. --facet company_type_exclude=outstaff.
Tags come from a curated dictionary read off the description, so treat an
exclusion as a discovery filter, not a fit test. Two ways it under-delivers: a
mention the dictionary does not recognise leaves the job tagless and in the
results, and excluding one language says nothing about the stack a job actually
runs on — --exclude-skill python still returns roles whose real core is cloud,
CI/CD or SQL.
Geography widens, it does not narrow. --region, --country and --city
are ONE OR-group: --region eu --country IT means "in Europe or in Italy" and
returns everything --region eu alone would. To search one country, pass the
country and drop the region. The three name a single concept — where — so
pickin