vitex-cli

vitex-cli

A thin command-line client for the hosted Vitex resume API — and a one-command MCP server so Claude Desktop, Claude Code, and Cursor can generate, refine, and download tailored resumes for you.

The API is the UI. Vitex compiles a tailored, ATS-optimized resume PDF and cover letter from a job description plus your background. This CLI is a thin wrapper over the hosted v1 HTTP API — no local pipeline, no Typst, no LLM. It is to Vitex what gh is to GitHub.

Install

npm install -g vitex-cli
# or run without installing:
npx vitex-cli --help

Requires Node.js >= 20.

Authentication

Mint an API key once while signed in to the web app (the raw token is shown once; only its SHA-256 hash is stored). Then:

export VITEX_API_KEY="vitex_xxx_yyy"

Every command reads VITEX_API_KEY (or --api-key <token>). The key is never echoed in output. The base URL defaults to https://www.vitex.org.nz and can be overridden with --api-url or VITEX_API_URL.

Billing (outcome-based)

You are charged 1 credit only when a job produces a compiled PDF (status: succeeded). Validation errors, LLM-step failures, and compilation failures are free. Refinements are free. New accounts start with 3 free credits.

Async job model

generate and refine return a job id immediately (status: queued). Poll it with vitex job <id> until succeeded | failed, then vitex pdf <id> — or pass --wait to let the CLI poll for you.

Commands

Command	What it does
vitex generate --jd <file|-> (--background <file|-> | --profile <id>) [--template <id>] [--wait] [-o out.pdf]	Create a resume job from a job description + background
vitex job <id>	Poll a job by id
vitex pdf <id> [-o out.pdf]	Download a succeeded job's PDF (default <id>.pdf)
vitex refine <id> --feedback <text|@file> [--scope resume|cover_letter|both] [--wait] [-o out.pdf]	Refine a succeeded resume (free)
vitex profiles list	List saved candidate backgrounds
vitex profiles get <id>	Show one profile with parsed data
vitex profiles create --background <file|-> [--label <text>] [--voice <file|->]	Save a reusable background
vitex profiles update <id> [--background <file|->] [--label <text>] [--voice <file|->]	Update a profile
vitex profiles delete <id>	Delete a profile
vitex profiles publish <id>	Publish a public /p/<slug> career endpoint
vitex profiles unpublish <id>	Close a published profile
vitex whoami	Verify your key and show your credit balance + tier (GET /api/v1/me; never spends credits)
vitex mcp	Run the stdio MCP server

Global flags

• --json — print raw JSON instead of a terse human line.
• --api-url <url> — override the base URL (default https://www.vitex.org.nz).
• --api-key <token> — override VITEX_API_KEY.
• -h, --help, --version.

Input conventions

• A - argument reads stdin (e.g. --jd -).
• --feedback also accepts @file to read the feedback from a file.

Exit codes

0 ok · 2 usage error · 3 API error · 4 poll timeout · 1 unexpected.

Examples

# Generate and wait, then save the PDF
vitex generate --jd jd.txt --background bg.txt --wait -o resume.pdf

# Pipe a JD in and reuse a saved profile, machine-readable output
echo "Senior Go engineer, payments, distributed systems" \
  | vitex generate --jd - --profile <profileId> --json

# Refine a succeeded resume and save the new version's PDF
vitex refine <jobId> --feedback "Lead with the payments impact." --wait -o v2.pdf

# Save a reusable background once
vitex profiles create --background bg.txt --label "My Background"

Errors print a single line to stderr in the shape error <CODE>: <message> (requestId), sourced from the API's machine-readable envelope.

MCP server (Claude Desktop / Claude Code / Cursor)

vitex mcp starts a Model Context Protocol server over stdio. Add it to your client's MCP config and the assistant can drive Vitex directly:

{
  "mcpServers": {
    "vitex": {
      "command": "npx",
      "args": ["-y", "vitex-cli", "mcp"],
      "env": { "VITEX_API_KEY": "vitex_xxx_yyy" }
    }
  }
}

For Claude Code, add the same server with:

claude mcp add vitex --env VITEX_API_KEY=vitex_xxx_yyy -- npx -y vitex-cli mcp

Tools

Each generate/refine tool blocks and polls internally, so the assistant gets a final result in one call. Every tool reads VITEX_API_KEY from the environment.

Tool	Purpose
get_account	Return your identity + credit balance + tier (read-only; check credits before generating)
generate_resume	Compile a tailored resume from jobDescription + background or profile_id (returns the final job incl. atsScore)
refine_resume	Refine a succeeded resume with feedback (+ optional scope)
get_resume	Fetch a job by id
download_pdf	Download a succeeded job's PDF to a temp file, return its path
list_profiles	List saved candidate backgrounds
create_profile	Save a reusable background
publish_profile / unpublish_profile	Toggle a profile's public career endpoint

Reference

• Full v1 API: https://github.com/ChanMeng666/easy-resume/blob/master/docs/api/v1.md
• OpenAPI spec: https://www.vitex.org.nz/openapi.yaml
• Agent playbook: https://www.vitex.org.nz/skill.md

Changelog

See CHANGELOG.md. Recent:

• 0.2.1 — MCP tool annotations on all 9 tools + mcpName for the official MCP Registry (no functional changes).
• 0.2.0 — whoami now uses the dedicated GET /api/v1/me endpoint (shows your credit balance + tier, not just a key check); new get_account MCP tool so agents can check credits before generating.
• 0.1.0 — Initial release.

Releasing

Maintainers: pushing a cli-v* tag publishes to npm via OIDC trusted publishing. See RELEASING.md.

License

MIT