hrmax-cli

CLI for the HRmax Open Platform. It wraps signing, encryption, async polling, and error codes so a local OpenClaw agent can create interviews, invite candidates, and fetch reports with a single command.

• Endpoints: production https://open-api.hrmax.jp, QA https://open-api.qa.hrmax.jp
• Output: human-readable messages on stderr, JSON on stdout for agents
• No public callback URL on the client side; use polling (report watch) instead of event webhooks

1. Requirements

• Node.js >= 18 (built-in fetch / crypto)

2. Install / Build

From npm:

npm i -g @h-and-i/hrmax-cli
hrmax-cli --help

From source:

npm install
npm run build

Artifacts go to dist/. Entry point: node dist/cli.js or npx hrmax-cli after linking.

3. Credentials (5 values provided by HRmax offline)

| Credential | Description | |-|-| | appKey | Customer unique ID | | appSecret | Signing secret (HmacSHA256) | | privateKey | AES-256 key (base64-encoded 32 bytes) | | uniqueCode | Company unique code | | openId | HR account identifier |

Two configuration methods (priority: env vars > config file):

Option A: environment variables

export HRMAX_APP_KEY=...
export HRMAX_APP_SECRET=...
export HRMAX_PRIVATE_KEY=...
export HRMAX_UNIQUE_CODE=...
export HRMAX_OPEN_ID=...
export HRMAX_ENV=prod   # prod | qa, default prod

Option B: local file ~/.hrmax/config.json (mode 600)

hrmax-cli config set \
  --app-key ... --app-secret ... --private-key ... \
  --unique-code ... --open-id ... --env prod
hrmax-cli config list   # overview only; secrets are masked

4. Safety notes

• Write operations (create interview, invite) are blocked by default; pass --yes explicitly. In production this creates real interviews and sends real emails.
• Any command accepts --dry-run to preview the request payload (business fields in plaintext, no secrets) without calling the API.
• Report PDF and face-image URLs expire in 10 minutes. report get/watch supports --download-pdf to save immediately.
• Reports contain personal / facial / evaluation data; the customer owns the lifecycle after export.

5. Command reference

Commodities

hrmax-cli commodity list                  # packages / dimensions / questions (read-only)

Custom questions

hrmax-cli question add --memo "Please introduce yourself" --yes
hrmax-cli question list --cur-page 0 --page-size 20

Create interview (async)

# Recommended dimensions/questions; --wait polls until interviewId is ready
hrmax-cli interview create \
  --commodity-id <commodityId> --job-name "Senior Programmer" \
  --job-category-code N000009 --wait --yes

# Custom dimensions/questions (skip recommendations)
hrmax-cli interview create --commodity-id <ID> --job-name X \
  --job-category-code N000009 --no-use-recommend \
  --select-dimensions-json '[{"dimensionId":"..","weightRatio":"0.5","selectQuestionList":[{"questionId":".."}]}]' \
  --yes

hrmax-cli interview create-status --task-id <taskId>
hrmax-cli interview list --cur-page 0 --page-size 20

Invite

# Email invite (repeat --candidate, up to 50)
hrmax-cli invite candidate --interview-id <ID> \
  --begin 202606071400 --end 202606091500 \
  --candidate "name=Yamada,[email protected]" --yes

# Public registration link
hrmax-cli invite public --interview-id <ID> \
  --begin 202606071400 --end 202606091500 --count 100 --yes

# Invite by unique ID (no email; requires invite public first)
hrmax-cli invite by-unique-id --interview-id <ID> --unique-id dym-0001 --yes

Reports (no local callback; use polling)

# One-shot query
hrmax-cli report get --interview-id <ID> --candidate-email [email protected] --download-pdf ./report.pdf

# Poll until the report is ready (interviewStatusCode=6), instead of event callbacks
hrmax-cli report watch --interview-id <ID> --candidate-email [email protected] \
  --interval 30 --timeout 3600 --download-pdf ./report.pdf

Dictionary

hrmax-cli dict job-category --search "game"   # look up jobCategoryCode (level3_code)

Event callback decrypt (optional, local verification)

hrmax-cli events decrypt --notify-contents '<ContentDto JSON>'

6. Typical OpenClaw agent flow

Customer machines usually have no public callback URL. Standard flow: create interview → invite → poll report.

# 1) Create interview and wait for interviewId
hrmax-cli interview create --commodity-id C --job-name "Role" \
  --job-category-code N000009 --wait --yes

# 2) Invite candidate
hrmax-cli invite candidate --interview-id I \
  --begin 202606071400 --end 202606091500 --candidate "name=X,[email protected]" --yes

# 3) Watch report; download PDF when ready (blocks until done)
hrmax-cli report watch --interview-id I --candidate-email [email protected] --download-pdf ./x.pdf

The agent reads stdout JSON for interviewId, answer links, and report payloads.

7. Deploy to a customer OpenClaw machine

npm i -g @h-and-i/hrmax-cli
hrmax-cli config set --app-key ... --app-secret ... --private-key ... \
  --unique-code ... --open-id ... --env prod

Or build from source: npm install && npm run build, then npm link.

Never bake credentials into the package. Use env vars or config set on the customer machine.

For an agent-oriented install checklist, see SETUP.md.

8. Known issues / TBD

• Candidate field names: the field table uses candidateEmail; some sample JSON uses email. This CLI sends {name, candidateEmail} per the field table. If validation fails in production, pass --candidates-json explicitly.
• privateKey is treated as a base64-encoded 32-byte key per the official SDK; if HRmax issues a different format, the CLI tries utf8/hex fallbacks and reports an error.