RoleWatch on the command line
Search and track
from the terminal.
rolewatch is a small CLI — and an MCP server — over the
same job API the site runs on. One API key lets an AI agent or a script search and open jobs, track
applications, work through your application mail and tailor a CV to a vacancy — all without a browser. (You still apply on the employer's site;
the CLI records that you did.)
Not on the terminal? Every way to connect an agent — MCP hosts, ChatGPT, and your own client.
# install — no Go needed curl -fsSL https://rolewatch.irfanmiral.com/install.sh | sh # authenticate once (key from /my/api-keys) rolewatch auth login --token fhk_… # discover the market, then search rolewatch facets rolewatch search "golang" --remote --region eu
commands
Discover
- RoleWatch facets
- Every filter's live values + counts — the vocabulary to filter by.
- RoleWatch market-fit --skills go,react
- How much of the live market your skills cover, and the gaps.
- RoleWatch search <query>
- List matching jobs (add --remote, --region, --company).
- RoleWatch job <slug>
- Show a job's full content.
- RoleWatch company <slug>
- Show a company and its open jobs.
Track applications & notes
- RoleWatch apply <slug>
- Mark a job applied for your account.
- RoleWatch save <slug>
- Bookmark a job (unsave to remove).
- RoleWatch stage <slug> <stage>
- Set the application stage.
- RoleWatch note <slug> <text>
- Attach a free-text note.
- RoleWatch my --filter applied
- Your tracked jobs (all|viewed|saved|applied).
- RoleWatch profile
- Your saved search profile — skills, seniority, regions.
Application mail
- RoleWatch inbox push --file mail.json
- Upload a batch your own client fetched (keyed by Message-ID, so a re-sync updates instead of duplicating).
- RoleWatch inbox list --unclassified --body
- The agent's work queue: unjudged mail with bodies inline, and nothing gets marked read.
- RoleWatch inbox triage <id> <signal>
- Record what a message is; a confident verdict moves the application forward.
- RoleWatch inbox list --link suggested
- Proposed links awaiting your word — inbox confirm / inbox reject.
- RoleWatch inbox list --link unlinked
- Mail with no application to attach to — inbox application records one from the message.
Contribute & moderate
- RoleWatch contribute <url>
- Hand RoleWatch a job link; a board we don't track yet gets added and crawled.
- RoleWatch contributions
- The boards you've contributed and their state.
- RoleWatch submissions
- Jobs you submitted; the review queue with pending/approve/reject (moderator).
- RoleWatch jobs add | edit <slug>
- Create or edit a job posting (moderator).
Start from rolewatch facets — it lists every filter's live
values so search and market-fit use real values, not guesses. Everything you
save, apply to and stage shows up on your Tracking board. stage takes a controlled value: preparing → applied → screening → responded → interview → offer → accepted, plus rejected / withdrawn.
Tailor a CV to a vacancy
After a match analysis, reframe your CV toward one job — grounded in what you actually did, never
fabricated — then export an ATS-ready PDF. cv context is the honest part: it splits the job's requirements into the ones your history already covers but
buries (reframe those) and the ones it doesn't (ask, don't invent), so an agent editing your CV
knows which is which.
RoleWatch cv context <id> # the match analysis to reframe toward RoleWatch cv get <id> # the CV document as JSON RoleWatch cv edit <id> --set … # one edit by path (--ops for a batch) RoleWatch cv render <id> --out cv.pdf
mcp
Same key, any AI host
rolewatch-mcp exposes the same search, market-fit and
tracking tools over the Model Context Protocol — so Claude Desktop, Claude Code or any MCP host can drive RoleWatch directly. It runs via npx; no global install.
It shares the CLI's credentials: if you've run rolewatch auth login, omit env and it reads ~/.rolewatch/creds.json.
{
"mcpServers": {
"RoleWatch": {
"command": "npx",
"args": ["-y", "https://rolewatch.irfanmiral.com/dl/rolewatch-mcp.tgz"],
"env": { "ROLEWATCH_TOKEN": "fhk_…" }
}
}
}for ai agents
Five skills, one per job
Each agent skill is named for the task, not the tool, so a host loads what the question needs instead of the whole surface. Drop them into a Claude Code (or compatible) skills directory — or install the plugin and get the slash commands too.
/plugin marketplace add strelov1/freehire-cli /plugin install rolewatch@rolewatch-cli
Every command takes --json for the raw API
payload — results to stdout, errors to stderr, non-zero exit on failure. The same
endpoints are in the API reference.
- /job-search rolewatch-job-search
- Read the saved profile, ground every filter in facets, search, and shortlist.
- /track-applications rolewatch-track-applications
- Where each application stands, stage moves, and reporting one that never answered.
- /market-fit rolewatch-market-fit
- Score a stack against live vacancy demand and put a number on every gap.
- /tailor-cv rolewatch-tailor-cv
- Reframe a CV toward one vacancy — every claim cited, nothing invented.
- /triage-inbox rolewatch-mail-triage
- Push a mail batch, judge each message, and drain the two link queues.
moderators
With the moderator role you can author postings:
rolewatch jobs add --url <url> --title "Senior Go Developer" --company Acme rolewatch jobs edit <slug> --title "Staff Go Developer"
Free and open source — no tracking, no lock-in. Read every line of the CLI ↗ and the MCP server ↗ on GitHub.