Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Other skills

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-search

About 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:

WriteMeans
"product owner"every quoted word must match, in any order (not a contiguous phrase)
-juniorexclude 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" sends title:product owner and matched 59,406 postings instead of 6,028.
  • Prefer one OR call 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.
  • --semantic when the need is described rather than named. "keep our payment systems secure" has no job title in it; with --semantic it 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 warning semantic search unavailable means 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

Read the complete source ↗