Agent CLI

The veref CLI is the headless agent surface for the same workflow that runs in the recruiter app chat, Claude, GPT, Codex, or another agent runtime. The UI agent and the CLI both call the same API-backed reference-check workflow.

Use it when an external agent needs to start, inspect, or advance reference checks without opening the recruiter UI.

Install

Install the published CLI:

npm install -g @verefwork/cli
veref --help

Or run it without a global install:

npm exec --package @verefwork/cli -- veref --help

For repo-local development:

bun install --frozen-lockfile
bun run veref -- help
bun run dev:cli

Login

For production use:

veref login

The login command opens the recruiter app, creates a tenant-scoped API key from the authenticated Clerk session, and stores it locally. On macOS the secret is stored in Keychain. On platforms without supported secure storage, prefer VEREF_API_KEY; plaintext file storage requires explicitly setting VEREF_ALLOW_PLAINTEXT_CLI_CREDENTIALS=1.

Use URL overrides only for local or staging environments:

export VEREF_API_URL=http://localhost:8787
export VEREF_APP_URL=http://localhost:3000
veref login

The CLI also accepts the legacy aliases VITAE_API_URL, VITAE_API_KEY, VITAY_API_URL, and VITAY_API_KEY.

API key

Create a tenant API key from the recruiter app or the API key management endpoint. For agents that start reference checks, grant:

["references:read", "references:write", "valuations:write", "reports:write"]

The API key supplies the tenant and recruiter identity. External agents should not send or choose tenantId or recruiterId.

Start a reference check

Flag-based start for the default candidate-intake loop:

veref references start \
  --candidate-first-name Ada \
  --candidate-last-name Lovelace \
  --candidate-email ada@example.com \
  --role-title "Founding Engineer"

This creates a candidate_pending request, queues the candidate intake invite, and returns the public candidate token. Candidate intake then collects permission, work history, and referee contacts before referee outreach starts.

Use manual_references when an agent or recruiter already has referee details and wants referee outreach to start directly:

veref references start \
  --launch-mode manual_references \
  --candidate-first-name Ada \
  --candidate-last-name Lovelace \
  --candidate-email ada@example.com \
  --role-title "Founding Engineer" \
  --contact-first-name Grace \
  --contact-last-name Hopper \
  --contact-email grace@example.com \
  --contact-phone +15555550100 \
  --contact-relationship "Former manager"

JSON-based start for agent runtimes:

cat reference-request.json | veref references start --stdin --format json

reference-request.json:

{
  "launchMode": "candidate_intake",
  "roleTitle": "Founding Engineer",
  "candidate": {
    "firstName": "Ada",
    "lastName": "Lovelace",
    "email": "ada@example.com",
    "stage": "sourced"
  },
  "contacts": [
    {
      "firstName": "Grace",
      "lastName": "Hopper",
      "email": "grace@example.com",
      "phone": "+15555550100",
      "relationship": "Former manager",
      "relationshipContext": "Reported to Grace at the previous company",
      "submittedByCandidate": false
    }
  ],
  "notes": "Started by external recruiting agent"
}

The response includes:

• request.id - stable reference request id
• request.status - candidate_pending for candidate intake, collecting for manual references
• request.candidateToken.token - public candidate intake token for candidate-intake launches
• candidateConsent.token - consent token generated for candidate-intake launches
• queued - candidate invite delivery preview or queued delivery metadata

Inspect a request

veref references get --request ref_req_123

JSON output is best for agents:

veref references get --request ref_req_123 --format json

Ask Veref headlessly

The same workspace agent used by the recruiter UI is available through the API-key route and CLI:

veref agent ask --message "What needs attention?" --format json

The agent uses the configured OpenRouter Gemini 3 model chain by default and can call the workspace/reference/report/ops tools it has scopes for.

Drive participant chats

Agents can also drive the public candidate/referee chat harness, including card submissions:

veref chat send --mode referee --token ref_token --message "Ready" --format json
veref chat send --mode referee --token ref_token --json card-submission.json --format json
veref chat complete --mode referee --token ref_token --format json

card-submission.json can be either the full API body or a raw card submission:

{
  "kind": "recommendation",
  "cardId": "recommendation_1",
  "choice": "yes",
  "rationale": "Would work with them again."
}

Advance lifecycle

Most flows do not need manual lifecycle calls because references start creates the request, queues candidate intake, or queues referee outreach for manual-reference launches. Use lifecycle commands when an agent is explicitly coordinating state.

veref references lifecycle \
  --request ref_req_123 \
  --action request_recruiter_review \
  --reason "All required reference evidence has been collected"

Supported lifecycle actions:

JSON lifecycle payloads are also supported:

veref references lifecycle --request ref_req_123 --json lifecycle.json

Draft, approve, and share valuation

veref references draft --request ref_req_123 --format json
veref references approve --request ref_req_123 --format json
veref references share --request ref_req_123 --format json

These commands use the same valuation/report endpoints as the recruiter UI.

Ops bridge

Agents can still use the ops commands to communicate with the tenant operations feed:

veref ops feed --tenant demo-agency
veref ops feed --format json
veref ops send --tenant demo-agency \
  --title "Need approval" \
  --body "Reference check is ready for recruiter review." \
  --from agent:codex \
  --to recruiter:owner \
  --priority high

Use references * for workflow state and ops * for coordination messages.