The ats-engine command scores a resume file with the VeriWorkly ATS Engine and prints the report. It reads PDF, DOCX, HTML, text, Markdown and JSON resume documents, optionally matches the resume against a job posting, and exits with a code a CI job can act on. It attaches the built-in language and region packs, so the library gives the same score when you call check(input, withLocales(DEFAULT_POLICY, BUILT_IN_LOCALES)). See Scoring for how it is built.

Install and run

PDF and DOCX files need the optional peers pdf-parse@2, [email protected] and mammoth. npx does not install optional peers on its own, so name them.

npm install -g @veriworkly/ats-engine pdf-parse@2 [email protected] mammoth
ats-engine check resume.pdf --job posting.txt

Node 22.12 or later is required. ats-engine --version prints the engine version.

Usage

ats-engine check <resume> [options]

Give exactly one resume file. A job posting is optional.

An unknown --region or --ats is a usage error that lists the accepted values. The accepted values come from the policy in use, so a custom --policy can define others.

AI analysis

--ai asks a model to explain the report and suggest improvements, with your own API key. The score never depends on it. The other AI flags are rejected without --ai.

Before anything leaves the machine, the CLI prints a notice on stderr naming the provider, host and model, and says that your name, email, phone number and links are replaced with placeholders first. Keyword suggestions are checked against the posting and the engine's keywords, and any that are not found there are dropped. The explanation, the fix order, the recommended improvements and the missing evidence are the model's own text and are not checked. See AI features.

Environment variables

The API key is read from the environment only, never from a flag, so it stays out of shell history and the process list.

ollama and any server on localhost, 127.0.0.1 or [::1] need no key. For any other host the CLI refuses to send a key over plain http.

Output

The text report shows the readiness score and verdict, the job match, requirements and missing keywords when there is a posting, the fields an ATS reads, each failed check with its fix, and the advice, which is never scored. Control characters in resume and posting text are removed before anything is printed.

With --json --ai, the report gains an ai member:

{
  "ai": {
    "provider": "anthropic",
    "model": "your-model-id",
    "insights": {
      "explanation": "...",
      "priorityOrder": ["..."],
      "recommendedImprovements": ["..."],
      "missingEvidence": ["..."],
      "keywordOpportunities": ["..."]
    },
    "rejected": [],
    "usage": { "inputTokens": 0, "outputTokens": 0 },
    "attempts": 1,
    "promptVersion": "default:..."
  }
}

usage is null when the provider did not report it. The member is absent when the analysis fails. See AI options for AtsAiResult.

Exit codes

Code 2 wins over code 1 when both happen: a failed --ai analysis does not hide the gate's answer. The CLI prints Readiness N is below --min-score M. on stderr.

Job URLs

--job-url reads a posting from the job board's public JSON API, never from the page. Only the board and the job id of your URL are used. The request goes to the board's fixed API host, redirects are not followed, the answer is capped at 20 MB and the wait at 20 seconds. This is the only request check makes without --ai.

Other sites are refused. Save the page and pass it with --job. A Greenhouse or Lever posting adds that ATS's notes to the advice unless --ats names another. Lever and Ashby name no employer, so the board's name stands in for it and is not suggested as a keyword.

Examples

Score a resume:

ats-engine check resume.pdf

Match against a saved posting and read the resume as a UK one:

ats-engine check resume.pdf --job posting.txt --region GB

Match against a posting on a job board:

ats-engine check resume.pdf --job-url https://boards.greenhouse.io/acme/jobs/1234567

Pipe the JSON to jq:

ats-engine check resume.pdf --json | jq '{score: .readinessScore, fixes: .prioritizedFixes}'

Gate a CI job. The command exits with 2 below 80:

ats-engine check resume.pdf --job posting.txt --min-score 80

Add an AI analysis with your own key:

export ANTHROPIC_API_KEY=your-key
ats-engine check resume.pdf --job posting.txt --ai --provider anthropic --model your-model-id

For a GitHub workflow, use the GitHub Action, which wraps this command. To call the engine from code, see the quick start.