CLI

neccessory is a zero-dependency Node (≥ 20) command line for the API. It is also a ready-made runtime for coding agents: every command has a --json mode and meaningful exit codes.

Setup

The package is not published to npm yet — run it from the repository:

node cli/bin/neccessory.mjs --help
npm install -g ./cli        # optional global install from the repo root

Credentials come from the environment. The key id and the secret are the ones Console → Keys issued you:

export NECCESSORY_KEY_ID=nk_live_...
export NECCESSORY_SECRET_KEY=nk_live_...
export NECCESSORY_BASE_URL=https://neccessory.com   # optional

neccessory auth test

Verifies the signature against POST /sdk/v1/auth/test and prints the key's facts: status, mode, allowed features, rate limit, monthly cloud-seconds quota and organization. If your clock drifts more than 30 s from the server a warning is printed — NCS1 signatures die at ±300 s.

neccessory measure <video>

The full batch tier round trip: hash → presigned upload → batch_video job → polling until the job settles, then a summary of the measurement (or the raw JSON with --json).

neccessory measure clip.mp4 --consent --features hrv,bp --user-ref u_42

--consent is mandatory — the video contains biometric data and the API refuses jobs without explicit consent. Accepted containers: .mp4, .mov, .webm. Useful flags: --webhook-url, --idempotency-key, --interval, --timeout, --include-assessment.

neccessory logs tail

Follows your key's usage log via GET /sdk/v1/logs (keyset cursor over (time, id); successful reads are not self-logged, so tailing never feeds itself). --since 1h sets the initial window, --once prints a single page, --json emits NDJSON — with the method and the machine errorCode that the plain output leaves out.

2026-08-24T12:00:01.234Z  success       /sdk/v1/cloud/jobs  12ms  req_…

Exit codes