hirify-cli 0.5.3 → 0.6.0

package/README.md

@@ -8,16 +8,26 @@ The npm package is **hirify-cli**; the executable is **hirify**.
 Node 18 or newer is required. Node 22 and 24 are the primary test lanes; 18 and 20 remain compatibility lanes.
 Windows, macOS and Linux use the same npm artifact. Native desktop browser acceptance is a separate release check.
 
+```sh
+npx -y hirify-cli@latest init
+```
+
+One command installs the CLI globally, installs the skill for the agents found on this computer
+(Claude Code, Codex, Cursor, OpenCode, Gemini CLI, Antigravity) and signs you in through the browser.
+Run it yourself or let your agent run it. `--no-install` and `--no-login` skip a step.
+
+The same steps one by one:
+
 ```sh
 npm install -g hirify-cli
-hirify --help
-npx skills add hirifyme/hirify-cli
+hirify skill
+hirify login
 ```
 
-For a one-off sign-in, run `npx hirify-cli login`.
+The skill is the agent's working rules. It comes inside the package, so it always matches the CLI;
+`npx skills add hirifyme/hirify-cli` installs the same skill through skills.sh.
 Without a global install, use `npx -y hirify-cli <command>`. npm may cache the package;
 use `npx -y hirify-cli@<version>` when the version must be reproducible.
-The skill supplies the agent's working rules; it does not install the executable.
 
 ## Sign in
 
@@ -27,15 +37,16 @@ hirify auth status --json
 ```
 
 Login prints a link first and tries the default browser when the terminal and environment permit it.
-A launcher result does not prove that a browser opened. Confirm access yourself; agents should ask
-you to do this. The callback listens only on a loopback IP, on a temporary port. PKCE and state
+A launcher result does not prove that a browser opened. Confirm access yourself; an agent that
+starts the sign-in asks you to do this. The callback listens only on a loopback IP, on a temporary port. PKCE and state
 protect the exchange. The CLI reports success after access has been saved, independently of the account summary.
 
 | Environment | Behavior |
 |---|---|
 | Local desktop terminal | Prints the link, tries the browser, waits for confirmation |
 | Linux without a display | Prints the link; does not promise or try a graphical browser |
-| Non-interactive terminal, CI, agent pipe | Fails promptly if a new browser sign-in is needed; use a key or explicit manual login |
+| Agent shell on a local desktop | Prints the link, tries the browser, waits for confirmation |
+| No terminal in CI, or no terminal and no display | Fails promptly if a new browser sign-in is needed; use a key or explicit manual login |
 | SSH | Requires explicit manual login and a forwarded fixed callback port, or a key |
 | Container | Use a key, or manual login only if the browser can reach the container's loopback callback |
 | WSL | Uses the maintained browser launcher when local and interactive; verify Windows-to-WSL loopback on your setup |
@@ -70,6 +81,7 @@ hirify vacancy read <slug>
 hirify vacancy reveal <slug>
 hirify vacancy hide <slug>...
 hirify company hide "<name>"
+hirify hidden list
 hirify profile list
 hirify vacancy apply <slug> --profile <id> --cover-file cover.txt
 ```
@@ -79,7 +91,7 @@ have a separate allowance. `hirify account show` supplies the current values. Sh
 read to assess fit, then reveal what fits. Applying sends a real application and cannot be recalled:
 get the person's approval first. External vacancies are applied to through the destination from `reveal`.
 Hiding a vacancy or a company is free and has no limit: it stops coming back in search and feeds,
-here and on the website. `--undo` brings it back.
+here and on the website. `--undo` brings it back; `hirify hidden list` shows what is hidden.
 
 The server defines search filters. Read `hirify filter guide`, preview with `filters.preview`, refine,
 and then run the final search. Do not infer filter names from an old example.

package/bin/lib/api.js

@@ -3,9 +3,9 @@ import { CliError } from './errors.js'
 import { trustedURL } from './config.js'
 import { requireJSON, retryDelay } from './http.js'
 import { accessRestrictedMessage, actionRequiredMessage } from './messages.js'
-const READS = new Set(['account.status', 'vacancies.search', 'feeds.list', 'feeds.vacancies', 'profiles.list', 'webhooks.list', 'filters.guide'])
+const READS = new Set(['account.status', 'vacancies.search', 'feeds.list', 'feeds.vacancies', 'profiles.list', 'webhooks.list', 'filters.guide', 'hidden.list'])
 const LISTS = new Set(['vacancies.search', 'feeds.list', 'feeds.vacancies', 'profiles.list', 'webhooks.list'])
-const OBJECTS = new Set(['account.status', 'vacancies.read', 'vacancies.reveal', 'applications.apply', 'feeds.create', 'feeds.set_delivery', 'webhooks.create', 'feedback.send', 'filters.guide'])
+const OBJECTS = new Set(['account.status', 'vacancies.read', 'vacancies.reveal', 'applications.apply', 'feeds.create', 'feeds.set_delivery', 'webhooks.create', 'feedback.send', 'filters.guide', 'hidden.list'])
 const isObject = value => value && typeof value === 'object' && !Array.isArray(value)
 const immutable = value => { if (value && typeof value === 'object') { for (const child of Object.values(value)) immutable(child); Object.freeze(value) }; return value }
 export function validateManifest(doc, origin) {

package/bin/lib/auth.js

@@ -73,7 +73,7 @@ export function createAuth({ config, store, http, signal, output, event, secrets
       if (current?.kind === 'oauth') { await access(); return { signed_in: true, already_signed_in: true, source: config.envKey ? 'environment' : 'oauth' } }
     }
     const info = environment()
-    if (!noBrowser && (!info.interactive || info.remote)) throw new CliError('interaction_required', 'This terminal cannot complete browser sign-in automatically. Use HIRIFY_KEY or hirify auth --stdin. For manual sign-in, use hirify login --no-browser; over SSH, also choose --callback-port and forward that port.')
+    if (!noBrowser && (info.remote || info.unattended || (!info.interactive && !info.gui))) throw new CliError('interaction_required', 'This terminal cannot complete browser sign-in automatically. Use HIRIFY_KEY or hirify auth --stdin. For manual sign-in, use hirify login --no-browser; over SSH, also choose --callback-port and forward that port.')
     if (info.remote && noBrowser && !port) throw new CliError('remote_callback_required', 'Browser callbacks must reach this machine. Choose --callback-port and forward that port over SSH, or use HIRIFY_KEY.')
     const generation = await store.beginLogin({ force })
     const endpoints = await discover()

package/bin/lib/browser.js

@@ -3,7 +3,12 @@ export function environment({ env = process.env, platform = process.platform, is
   const remote = Boolean(env.SSH_CONNECTION || env.SSH_TTY)
   const wsl = platform === 'linux' && Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP)
   const gui = platform !== 'linux' || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY || wsl)
-  return { remote, wsl, interactive: isTTY, gui, canOpen: isTTY && !remote && gui }
+  // A build server without a terminal has nobody to confirm access, whatever its platform
+  // says about a display. A person at a terminal is unaffected.
+  const unattended = Boolean(env.CI) && !isTTY
+  // An agent runs commands without a terminal of its own, on a desktop where a browser can open
+  // and the person can confirm. So a missing terminal alone does not rule sign-in out.
+  return { remote, wsl, interactive: isTTY, gui, unattended, canOpen: !remote && !unattended && gui }
 }
 export const canOpenBrowser = options => environment(options).canOpen
 /** A launcher acknowledgement is not proof that a browser window appeared. */

package/bin/lib/cli.js

@@ -1,10 +1,11 @@
 import { CliError, redact, safeText } from './errors.js'
 const ARGUMENTS = { auth: '[<key>]', update: '[<version>]', 'vacancy search': '[<query>]', 'vacancy read': '<slug>', 'vacancy reveal': '<slug>', 'vacancy apply': '<slug>', 'vacancy hide': '<slug>...', 'company hide': '[<name>...]', 'feed show': '<id>', 'feed create': '<name>', 'feed deliver': '<id>', 'webhook create': '<name> <url>', 'feedback send': '<bug|feature> <title>', 'api call': '<capability>', 'capabilities show': '<capability>' }
 const GLOBAL = ['json', 'fields', 'error-format', 'debug', 'timeout', 'help']
-export const BOOLEAN_FLAGS = new Set(['json', 'debug', 'help', 'force', 'no-browser', 'stdin', 'telegram', 'no-telegram', 'no-webhook', 'check', 'rollback', 'undo'])
+export const BOOLEAN_FLAGS = new Set(['json', 'debug', 'help', 'force', 'no-browser', 'no-install', 'no-login', 'stdin', 'telegram', 'no-telegram', 'no-webhook', 'check', 'rollback', 'undo'])
 export const COMMANDS = {
   intro: { args: [0, 0], description: 'what this can do, and in what order' },
   version: { args: [0, 0], description: 'installed version' },
+  init: { args: [0, 0], flags: ['no-install', 'no-login', 'no-browser', 'callback-port'], description: 'install the CLI and the skill, then sign in' },
   skill: { args: [0, 0], description: 'install the working rules for your agent' },
   login: { args: [0, 0], flags: ['force', 'no-browser', 'callback-port'], description: 'sign in through your browser' },
   logout: { args: [0, 0], description: 'sign out on this computer' },
@@ -19,6 +20,7 @@ export const COMMANDS = {
   'vacancy apply': { args: [1, 1], flags: ['profile', 'cover', 'cover-file'], description: 'send a real application; ask the person first' },
   'vacancy hide': { args: [1, 100], flags: ['undo'], description: 'hide vacancies from your search and feeds; free, no limit' },
   'company hide': { args: [0, 100], flags: ['vacancy', 'undo'], description: 'hide a company by name, or by --vacancy <slug>; free, no limit' },
+  'hidden list': { args: [0, 0], flags: ['page', 'limit'], description: 'what you hid: vacancies and companies' },
   'feed list': { args: [0, 0], description: 'your saved feeds' },
   'feed show': { args: [1, 1], flags: ['limit', 'page'], description: 'vacancies in a feed' },
   'feed create': { args: [1, 1], flags: ['filters', 'telegram', 'no-telegram', 'webhook'], description: 'save a search and its delivery settings' },
@@ -97,11 +99,11 @@ export function parse(argv) {
   if (name === 'auth' && words.length && (!words[0].trim() || /[\r\n]/.test(words[0]))) throw new CliError('invalid_arguments', 'The key must be nonempty and contain no line breaks.')
   if (name === 'feedback send' && (!['bug', 'feature'].includes(words[0]) || !value('body'))) throw new CliError('invalid_arguments', 'Use hirify feedback send bug|feature <title> --body <text>.')
   const args = [...parsed.options].flatMap(([key, values]) => values.map(v => v === true ? `--${key}` : `--${key}=${v}`))
-  return { name, words, args, values: Object.fromEntries([...parsed.options].map(([k, v]) => [k, v[0]])), json: Boolean(value('json')), errorJSON: value('error-format') === 'json', timeout: Number(value('timeout') || (name === 'login' ? 360 : name === 'update' ? 300 : 30)) * 1000 }
+  return { name, words, args, values: Object.fromEntries([...parsed.options].map(([k, v]) => [k, v[0]])), json: Boolean(value('json')), errorJSON: value('error-format') === 'json', timeout: Number(value('timeout') || (name === 'init' ? 600 : name === 'login' ? 360 : name === 'update' ? 300 : 30)) * 1000 }
 }
 export function help(topic = '') {
   const entries = Object.entries(COMMANDS).filter(([name]) => !topic || name === topic || name.startsWith(topic + ' '))
-  return `hirify - job search for AI agents\n\n${(entries.length ? entries : Object.entries(COMMANDS)).map(([name, spec]) => `  hirify ${(name + (ARGUMENTS[name] ? ' ' + ARGUMENTS[name] : '')).padEnd(35)} ${spec.description}${spec.flags?.length ? `\n    ${spec.flags.map(f => '--' + f + (BOOLEAN_FLAGS.has(f) ? '' : ' <value>')).join('  ')}` : ''}`).join('\n')}\n\nGlobal options: --json, --fields a,b, --error-format json|text, --timeout <seconds>, --debug, --help.\nUse -- to end options; --name=value and --name value are supported.\nLists and search are free. Vacancy read, reveal and apply have separate allowances.\nCheck them with hirify account show. Apply sends a real application: ask the person first.\nLocal agents reuse saved sign-in when allowed. Token renewal needs write access.\nSandbox access denied: request permission for the command; do not copy tokens.\nHeadless/CI: HIRIFY_KEY or hirify auth --stdin. Manual login: --no-browser.\nSSH: forward the chosen --callback-port to the same loopback port on the CLI host.\nRules for your agent: npx skills add hirifyme/hirify-cli\n`
+  return `hirify - job search for AI agents\n\n${(entries.length ? entries : Object.entries(COMMANDS)).map(([name, spec]) => `  hirify ${(name + (ARGUMENTS[name] ? ' ' + ARGUMENTS[name] : '')).padEnd(35)} ${spec.description}${spec.flags?.length ? `\n    ${spec.flags.map(f => '--' + f + (BOOLEAN_FLAGS.has(f) ? '' : ' <value>')).join('  ')}` : ''}`).join('\n')}\n\nGlobal options: --json, --fields a,b, --error-format json|text, --timeout <seconds>, --debug, --help.\nUse -- to end options; --name=value and --name value are supported.\nLists and search are free. Vacancy read, reveal and apply have separate allowances.\nCheck them with hirify account show. Apply sends a real application: ask the person first.\nLocal agents reuse saved sign-in when allowed. Token renewal needs write access.\nSandbox access denied: request permission for the command; do not copy tokens.\nHeadless/CI: HIRIFY_KEY or hirify auth --stdin. Manual login: --no-browser.\nSSH: forward the chosen --callback-port to the same loopback port on the CLI host.\nSet up the CLI, the skill and sign-in: hirify init. The skill alone: hirify skill\n`
 }
 export function createOutput({ stdout = process.stdout, stderr = process.stderr, json = false, errorJSON = false, secrets = new Set() } = {}) {
   let closed = false

package/bin/lib/commands.js

@@ -238,6 +238,11 @@ async function cmdVacancyRead(args, words) {
       ['page', d.url],
     ])
     if (rows.length) console.log('\n' + rows.join('\n'))
+    if (d.hidden) {
+      console.log(d.hidden_reason === 'company'
+        ? '\nHidden: its company is hidden, so it stays out of search and feeds.'
+        : '\nHidden: you hid this vacancy, so it stays out of search and feeds.')
+    }
 
     const text = d.description ? asText(d.description) : ''
     console.log(text ? `\n${text}\n` : '\nThis vacancy has no text on it.\n')
@@ -295,20 +300,60 @@ async function cmdVacancyReveal(args, words) {
  * list the website's "Hide" button writes, so it works in both directions. Free and not
  * limited; --undo brings them back. Up to 100 per call: the server takes them in one request.
  */
-function printHidden(d, one, many, undo) {
-  const n = count(d.updated) ?? 0
-  const noun = n === 1 ? one : many
-  console.log(undo
-    ? `${n} ${noun} unhidden.`
-    : `${n} ${noun} hidden. ${n === 1 ? 'It no longer appears' : 'They no longer appear'} in your search and feeds.`)
-  if (Array.isArray(d.not_found) && d.not_found.length) console.log(`not found: ${d.not_found.join(', ')}`)
+// What each result status means, in the words a person reads. The server names the outcome of
+// every item, so nobody has to search again to find out whether a hide took.
+const HIDE_STATUS = {
+  hidden: 'hidden', already_hidden: 'already hidden', unhidden: 'unhidden',
+  not_hidden: 'was not hidden', not_found: 'not found', no_company: 'no company name',
+}
+
+function printHidden(d, many, undo) {
+  const results = Array.isArray(d.results) ? d.results : []
+  const label = (r) => r.company ? `${r.company} (${r.slug})` : (r.name ?? r.slug ?? '-')
+  const width = Math.max(0, ...results.map((r) => (HIDE_STATUS[r.status] ?? String(r.status)).length))
+  for (const r of results) {
+    const status = HIDE_STATUS[r.status] ?? String(r.status)
+    console.log(`${status.padEnd(width)}  ${label(r)}${r.still_hidden_by_company ? '  (still hidden: its company is hidden)' : ''}`)
+  }
+  const summary = Object.entries(d.summary ?? {}).map(([k, n]) => `${n} ${HIDE_STATUS[k] ?? k}`).join(', ')
+  if (summary) console.log(`\n${summary}.`)
+  if (!undo && (d.summary?.hidden || d.summary?.already_hidden)) console.log(`Hidden ${many} do not appear in your search and feeds. See them: hirify hidden list`)
+}
+
+/** Everything the person hid, here or on the website: vacancies page by page, all companies. */
+async function cmdHiddenList(args) {
+  const query = new URLSearchParams()
+  const page = flag(args, '--page')
+  const limit = flag(args, '--limit')
+  if (page) query.set('page', page)
+  if (limit) query.set('per_page', limit)
+  const body = await callCapability('hidden.list', { query })
+  const d = body?.data ?? {}
+  const m = body?.meta ?? {}
+  out(body, () => {
+    const vacancies = d.vacancies ?? []
+    const companies = d.companies ?? []
+    console.log(`Hidden vacancies: ${d.totals?.vacancies ?? vacancies.length}`)
+    for (const v of vacancies) {
+      console.log(`  ${v.slug}\n    ${[v.title, v.company].filter(Boolean).join(' · ')}${v.archived ? '  [archived]' : ''}  hidden ${dateOnly(v.hidden_at) ?? '-'}`)
+    }
+    if (m.last_page > 1) console.log(`  page ${m.page} of ${m.last_page}: --page <n>`)
+    console.log(`\nHidden companies: ${d.totals?.companies ?? companies.length}`)
+    for (const c of companies) {
+      const n = count(c.live_vacancies) ?? 0
+      console.log(`  ${c.name}  (${n} live ${n === 1 ? 'vacancy' : 'vacancies'})  hidden ${dateOnly(c.hidden_at) ?? '-'}`)
+    }
+    if (vacancies.length || companies.length) {
+      console.log('\nUnhide: hirify vacancy hide <slug> --undo  |  hirify company hide "<name>" --undo')
+    }
+  })
 }
 
 async function cmdVacancyHide(args, words) {
   if (!words.length) die('at least one vacancy slug is required: hirify vacancy hide <slug>...')
   const undo = args.includes('--undo')
   const body = await callCapability('vacancies.hide', { payload: { slugs: words, hidden: !undo } })
-  out(body, () => printHidden(body?.data ?? {}, 'vacancy', 'vacancies', undo))
+  out(body, () => printHidden(body?.data ?? {}, 'vacancies', undo))
 }
 
 async function cmdCompanyHide(args, words) {
@@ -317,7 +362,7 @@ async function cmdCompanyHide(args, words) {
   const undo = args.includes('--undo')
   const payload = { hidden: !undo, ...(words.length ? { names: words } : {}), ...(vacancy ? { slugs: [vacancy] } : {}) }
   const body = await callCapability('companies.hide', { payload })
-  out(body, () => printHidden(body?.data ?? {}, 'company', 'companies', undo))
+  out(body, () => printHidden(body?.data ?? {}, 'companies', undo))
 }
 
 /**
@@ -566,6 +611,9 @@ const INTRO = `hirify - job search for AI agents
 Hirify is a job board. This CLI is how an agent works it for someone: the same vacancies, the
 same saved filters and the same account they have at hirify.me.
 
+Setting up
+  npx -y hirify-cli@latest init installs this CLI and the agent's skill, then opens sign-in.
+
 Signing in
   hirify login prints a link and tries the browser when available. A person confirms access.
   Manual sign-in: hirify login --no-browser. For automation, use HIRIFY_KEY or hirify auth --stdin; get a key at
@@ -646,7 +694,7 @@ If a command you need is not here
   they say what a thing costs and what a refusal means, and this one cannot.
 
 If you are an agent
-  Install the working rules once: npx skills add hirifyme/hirify-cli. They cover the order
+  Install the working rules once: hirify skill. They cover the order
   above, what needs the person's permission before you do it, and what each refusal means.
 
 Use --json for structured results and --error-format=json for structured errors.
@@ -837,18 +885,12 @@ async function cmdFilterGuide() {
   out(res.body, () => console.log(guide))
 }
 
-/** The skill ships through skills.sh now: one command installs it into every harness. */
-function cmdSkill() {
-  console.log('The rules for your agent install with one command:\n\n  npx skills add hirifyme/hirify-cli\n')
-  console.log('It puts them where your agent reads them: Claude Code, Codex, Cursor, OpenCode and others.')
-}
-
 
 return {
-  intro: cmdIntro, skill: cmdSkill,
+  intro: cmdIntro,
   'account show': cmdAccountShow,
   'vacancy search': cmdVacancySearch, 'vacancy read': cmdVacancyRead, 'vacancy reveal': cmdVacancyReveal, 'vacancy apply': cmdVacancyApply,
-  'vacancy hide': cmdVacancyHide, 'company hide': cmdCompanyHide,
+  'vacancy hide': cmdVacancyHide, 'company hide': cmdCompanyHide, 'hidden list': cmdHiddenList,
   'feed list': cmdFeedList, 'feed show': cmdFeedShow, 'feed create': cmdFeedCreate, 'feed deliver': cmdFeedDeliver,
   'profile list': cmdProfileList, 'webhook list': cmdWebhookList, 'webhook create': cmdWebhookCreate,
   'feedback send': cmdFeedbackSend, 'filter guide': cmdFilterGuide, 'api call': cmdApiCall,

package/bin/lib/main.js

@@ -55,7 +55,7 @@ export async function main(argv = process.argv.slice(2), { baseRoot = ownRoot, b
     const auth = createAuth({ config, store, http, signal, output, event, secrets })
     const api = createApi({ config, http, auth, output })
     const updater = createUpdater({ config, http, signal, output, event, packageRoot: ownRoot, baseRoot, baseVersion })
-    const local = ['auth', 'auth status', 'logout', 'doctor', 'skill', 'update'].includes(command.name)
+    const local = ['auth', 'auth status', 'logout', 'doctor', 'init', 'skill', 'update'].includes(command.name)
     if (!skipUpdate && !local) next = await updater.automatic()
     if (next) {
       // Dispose every timer and signal handler before handing off, at most once per invocation.
@@ -63,6 +63,40 @@ export async function main(argv = process.argv.slice(2), { baseRoot = ownRoot, b
       const result = await auth.login({ force: Boolean(command.values.force), noBrowser: Boolean(command.values['no-browser']), port: Number(command.values['callback-port'] || 0), consentMs: Math.min(command.timeout, 300000) })
       if (command.json) output.json(result)
       else { output.console.log(result.already_signed_in ? 'Already signed in. Use hirify login --force to sign in again.' : 'Signed in. Access saved on this computer.'); if (result.environment_override || result.source === 'environment') output.progress('HIRIFY_KEY is set and takes precedence over the saved sign-in.'); output.console.log('Your plan and allowances: hirify account show') }
+    } else if (command.name === 'skill') {
+      const { installSkill, describeSkill } = await import('./setup.js')
+      const result = installSkill({ packageRoot: ownRoot, env: config.env })
+      if (command.json) output.json(result); else for (const line of describeSkill(result)) output.console.log(line)
+      if (result.agents.some(item => !item.installed)) exitCode = 1
+    } else if (command.name === 'init') {
+      // The steps that need nobody go first; sign-in waits for the person and comes last.
+      const { installGlobally, installSkill, describeSkill } = await import('./setup.js')
+      const result = {}
+      let skillRoot = ownRoot
+      if (!command.values['no-install']) {
+        output.progress('Installing the Hirify CLI...')
+        // A newer CLI found on this computer stays, and the skill is taken from it.
+        const { root, ...cli } = await installGlobally({ version: pkg.version, signal, env: config.env })
+        result.cli = cli
+        if (root) skillRoot = root
+      }
+      try { result.skill = installSkill({ packageRoot: skillRoot, env: config.env }) }
+      catch (error) { if (!(error instanceof CliError)) throw error; result.skill = { error: error.code, message: error.message, agents: [] } }
+      if (!command.values['no-login']) {
+        let source = 'none'
+        try { source = auth.status().source } catch {}
+        if (['environment', 'key'].includes(source)) result.sign_in = { signed_in: true, already_signed_in: true, source }
+        else try { result.sign_in = await auth.login({ noBrowser: Boolean(command.values['no-browser']), port: Number(command.values['callback-port'] || 0), consentMs: Math.min(command.timeout, 300000) }) }
+        catch (error) { if (!(error instanceof CliError) || signal.aborted) throw error; result.sign_in = { signed_in: false, error: error.code, message: error.message } }
+      }
+      if (command.json) output.json(result)
+      else {
+        if (result.cli) output.console.log(result.cli.installed ? `Hirify CLI ${result.cli.version} is installed. The command is: hirify` : `The CLI could not be installed globally (${result.cli.reason}). Every command still works as: npx -y hirify-cli <command>`)
+        if (result.skill.error) output.console.log(result.skill.message); else for (const line of describeSkill(result.skill)) output.console.log(line)
+        if (result.sign_in) output.console.log(result.sign_in.signed_in ? (result.sign_in.already_signed_in ? 'Already signed in.' : 'Signed in. Access saved on this computer.') : result.sign_in.message)
+        if (result.sign_in?.signed_in) output.console.log('Next: ask your agent to look at your Hirify profile and saved searches.')
+      }
+      if (result.cli?.installed === false || result.skill.error || result.skill.agents.some(item => !item.installed) || result.sign_in?.signed_in === false) exitCode = 1
     } else if (command.name === 'auth') {
       secrets.add(command.words[0])
       await store.commit({ kind: 'key', access_token: command.words[0] })
@@ -90,8 +124,7 @@ export async function main(argv = process.argv.slice(2), { baseRoot = ownRoot, b
       else { const result = await updater.install(target, { pin: Boolean(command.words[0] || config.env.HIRIFY_VERSION_PIN) }); if (command.json) output.json(result); else output.console.log(`Hirify CLI ${result.version} is ready for the next command.${result.pinned ? ' This version is pinned.' : ''}`) }
     } else {
       const commands = createCommands({ api, output, config, signal, event, fields: command.values.fields })
-      if (command.name === 'skill' && command.json) output.json({ install: 'npx skills add hirifyme/hirify-cli' })
-      else await commands[command.name](command.args, command.words)
+      await commands[command.name](command.args, command.words)
     }
   } catch (error) { exitCode = output.error(error) }
   finally { await cleanup(); await output.flush().catch(() => { exitCode = 1 }); output.dispose() }

package/bin/lib/setup.js

@@ -0,0 +1,102 @@
+import { existsSync, mkdirSync, cpSync, rmSync, symlinkSync, lstatSync, realpathSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+import semver from 'semver'
+import { CliError } from './errors.js'
+import { PACKAGE_NAME, runProcess } from './update.js'
+
+export const SKILL_NAME = 'hirify'
+
+/**
+ * Where each agent reads its global skills, and the directory whose presence means the agent is
+ * installed on this computer. The paths follow the registry of the `skills` tool, so the skill
+ * lands in the same place whether it comes from here or from `npx skills add`.
+ */
+export function agentDirectories({ env = process.env, home = homedir() } = {}) {
+  const config = env.XDG_CONFIG_HOME?.trim() || join(home, '.config')
+  const claude = env.CLAUDE_CONFIG_DIR?.trim() || join(home, '.claude')
+  const codex = env.CODEX_HOME?.trim() || join(home, '.codex')
+  return [
+    { name: 'Claude Code', home: claude, skills: join(claude, 'skills') },
+    { name: 'Codex', home: codex, skills: join(codex, 'skills') },
+    { name: 'Cursor', home: join(home, '.cursor'), skills: join(home, '.cursor', 'skills') },
+    { name: 'OpenCode', home: join(config, 'opencode'), skills: join(config, 'opencode', 'skills') },
+    { name: 'Gemini CLI', home: join(home, '.gemini'), skills: join(home, '.gemini', 'skills') },
+    { name: 'Antigravity', home: join(home, '.gemini', 'antigravity'), skills: join(home, '.gemini', 'antigravity', 'skills') },
+  ]
+}
+
+const entry = path => { try { return lstatSync(path) } catch (error) { if (error.code === 'ENOENT') return null; throw error } }
+const real = path => { try { return realpathSync(path) } catch { return path } }
+// Removing a link removes the link, never the directory it points to.
+const remove = path => { if (entry(path)) rmSync(path, { recursive: true, force: true }) }
+const readJSON = file => { try { return JSON.parse(readFileSync(file, 'utf8')) } catch { return null } }
+// OS messages may carry private paths, so only the code is reported.
+const reason = error => ['EACCES', 'EPERM', 'EROFS', 'ENOSPC', 'EDQUOT', 'ENOTDIR', 'ENOENT', 'EEXIST', 'ELOOP'].includes(error?.code) ? error.code : 'unknown'
+
+/**
+ * Install the skill carried by this package: one shared copy under `~/.agents/skills`, linked into
+ * every agent found here. The skill comes from the package of the CLI it is for, so the two match.
+ * An agent that cannot be written to is reported and does not stop the others.
+ */
+export function installSkill({ packageRoot, env = process.env, home = homedir(), platform = process.platform } = {}) {
+  const source = join(packageRoot, 'skills', SKILL_NAME)
+  if (!existsSync(join(source, 'SKILL.md'))) throw new CliError('skill_missing', 'This installation does not carry the skill. Install it with: npx skills add hirifyme/hirify-cli')
+  const shared = join(home, '.agents', 'skills')
+  const path = join(shared, SKILL_NAME)
+  try {
+    mkdirSync(shared, { recursive: true })
+    remove(path)
+    cpSync(source, path, { recursive: true })
+  } catch (error) { throw new CliError('skill_install_failed', `Could not save the skill (${reason(error)}). This command needs write access to the home directory.`) }
+  const agents = []
+  for (const agent of agentDirectories({ env, home })) {
+    if (!existsSync(agent.home)) continue
+    try {
+      mkdirSync(agent.skills, { recursive: true })
+      // An agent whose skills directory already is the shared one needs no link of its own.
+      const parent = real(agent.skills)
+      if (parent === real(shared)) { agents.push({ agent: agent.name, installed: true }); continue }
+      const target = join(parent, SKILL_NAME)
+      remove(target)
+      try {
+        // A junction needs no elevated rights on Windows; elsewhere the link stays relative.
+        if (platform === 'win32') symlinkSync(real(path), target, 'junction')
+        else symlinkSync(relative(parent, real(path)), target, 'dir')
+      } catch { cpSync(source, target, { recursive: true }) }
+      agents.push({ agent: agent.name, installed: true })
+    } catch (error) { agents.push({ agent: agent.name, installed: false, reason: reason(error) }) }
+  }
+  return { skill: SKILL_NAME, path, agents }
+}
+
+/**
+ * Put the CLI on PATH with the person's own npm and its settings: the environment goes to npm as
+ * it is, because what npx adds to it is the same configuration, already resolved. A failure is a
+ * result, not an error: without a global installation every command still runs as
+ * `npx -y hirify-cli <command>`. A newer global installation is kept, never downgraded, and its
+ * `root` says where the skill that matches it is.
+ */
+export async function installGlobally({ version, signal, env = process.env, run = runProcess } = {}) {
+  const options = { signal, env }
+  let root
+  try { root = await run('npm', ['root', '--global'], { ...options, timeout: 10000 }) }
+  catch (error) { if (signal?.aborted) throw error; return { installed: false, reason: 'npm_unavailable' } }
+  if (root.code !== 0 || !root.stdout.trim()) return { installed: false, reason: 'npm_unavailable' }
+  const location = join(root.stdout.trim(), PACKAGE_NAME)
+  const current = readJSON(join(location, 'package.json'))
+  if (current?.name === PACKAGE_NAME && semver.valid(current.version) && semver.gte(current.version, version)) return { installed: true, version: current.version, changed: false, ...(semver.gt(current.version, version) && { root: location }) }
+  let result
+  try { result = await run('npm', ['install', '--global', '--ignore-scripts', '--no-audit', '--no-fund', `${PACKAGE_NAME}@${version}`], { ...options, timeout: 180000 }) }
+  catch (error) { if (signal?.aborted) throw error; return { installed: false, reason: 'install_failed' } }
+  return result.code === 0 ? { installed: true, version, changed: true } : { installed: false, reason: 'install_failed' }
+}
+
+/** Lines a person reads after `hirify skill` or `hirify init`. */
+export function describeSkill(result) {
+  const done = result.agents.filter(item => item.installed).map(item => item.agent)
+  const failed = result.agents.filter(item => !item.installed).map(item => `${item.agent} (${item.reason})`)
+  const lines = [done.length ? `The skill is installed for ${done.join(', ')}.` : `The skill is saved in ${result.path}. No supported agent was found on this computer.`]
+  if (failed.length) lines.push(`It could not be installed for ${failed.join(', ')}. Check that the agent's skills directory is a folder you can write to, then run hirify skill.`)
+  return lines
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "hirify-cli",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "hirify-cli",
-      "version": "0.5.3",
+      "version": "0.6.0",
       "license": "Apache-2.0",
       "dependencies": {
         "cross-spawn": "7.0.6",

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "hirify-cli",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Hirify CLI for AI agents: browser sign-in, job feeds, search, reading a vacancy in full, contacts to apply to, and applying on Hirify.",
   "bin": {
     "hirify": "bin/hirify.js"
   },
   "scripts": {
-    "test": "node --test scripts/test.mjs scripts/runtime.test.mjs scripts/network.test.mjs scripts/update.test.mjs scripts/storage.test.mjs",
+    "test": "node --test scripts/test.mjs scripts/runtime.test.mjs scripts/network.test.mjs scripts/update.test.mjs scripts/storage.test.mjs scripts/setup.test.mjs",
     "build": "node scripts/build.mjs",
     "test:package": "node scripts/verify-package.mjs",
     "prepublishOnly": "node scripts/prepublish-check.mjs",

package/skills/hirify/SKILL.md

@@ -10,16 +10,17 @@ has every command in full, and `hirify intro` is the server's guide.
 
 ## Setup and automation
 
-Package: `hirify-cli`; command: `hirify`; Node >=18. Prefer Node 22 or 24.
-Without a global install use `npx -y hirify-cli <command>` (npm may cache it).
-Offer `npm install -g hirify-cli` only with permission. Global installs can update automatically;
-for reproducible work use an exact version and `HIRIFY_NO_AUTO_UPDATE=1`.
-
-A person runs `hirify login` and confirms the printed link. The CLI tries a browser only when
-appropriate. Do not run login for them. `--no-browser` is manual callback login, not device flow.
-SSH needs `--callback-port` with a matching SSH local port forward. Local agents reuse the person's
-saved sign-in when permitted to access the same configuration directory. CI and separate containers
-can use `HIRIFY_KEY` or `hirify auth --stdin`; never put a key in a command, log or chat.
+Package: `hirify-cli`; command: `hirify`; Node >=18.
+If `hirify` is missing, run `npx -y hirify-cli@latest init`: it installs the CLI and this skill,
+then signs in. Until then use `npx -y hirify-cli <command>`. Global installs update themselves;
+pin an exact version with `HIRIFY_NO_AUTO_UPDATE=1`.
+
+To sign in, run `hirify login`; the person confirms access in the browser within five minutes.
+It fails at once over SSH, and without a terminal in CI or with no display. `--no-browser` is
+manual callback login. SSH needs `--callback-port` with a matching SSH local port forward. Local
+agents reuse the person's saved sign-in when permitted to access the same configuration directory.
+CI and separate containers can use `HIRIFY_KEY` or `hirify auth --stdin`; never put a key in a
+command, log or chat.
 `hirify auth status --json` identifies the local source. Environment keys override saved access;
 logout is local and does not unset them. Use `hirify login --force` to replace expired access.
 
@@ -49,7 +50,7 @@ no permission. Sending, saving and configuring do.
 3. `vacancy read <slug>` to assess fit from the full text rather than a headline.
 4. `vacancy reveal <slug>` only for vacancies that still fit after reading.
 5. Apply only after the person's approval and the rules below.
-6. `vacancy hide` / `company hide` what the user rejected; free, unlimited.
+6. `vacancy hide`/`company hide` what the user rejected; `hidden list` shows it.
 
 ## Searching
 

package/skills/hirify/reference.md

@@ -62,10 +62,14 @@ outlives every change to them.
 
 ## Signing in
 
-A person runs `hirify login`, opens the printed link and confirms access. The CLI tries a browser
-only where appropriate. `--no-browser` disables launching but still needs a reachable callback;
-SSH requires `--callback-port` and a matching port forward. CI/agents should use `HIRIFY_KEY` or
-`hirify auth --stdin`. A new non-interactive browser login fails promptly unless manual mode was explicit.
+`hirify login` prints a link, opens the browser where it can and waits until the person confirms
+access. An agent on a local desktop may run it and ask the person to confirm. `--no-browser`
+disables launching but still needs a reachable callback; SSH requires `--callback-port` and a
+matching port forward. CI should use `HIRIFY_KEY` or `hirify auth --stdin`. Over SSH, and without
+a terminal in CI or with no display, a new browser login fails promptly unless manual mode was
+explicit.
+`npx -y hirify-cli@latest init` installs the CLI and this skill and then signs in; `hirify skill`
+installs the skill alone.
 Access is stored under an absolute XDG_CONFIG_HOME or `~/.config/hirify`, with private file permissions
 and atomic writes. `auth status --json` shows its source. `logout` clears local access, not server
 access or environment keys. `HIRIFY_KEY` wins over the saved sign-in. Use `login --force` to replace