Skip to main content

CLI reference

node bin/viaid.mjs <command> [args]

Commands split into two sides: S2 commands are what a developer runs to badge and log an agent they're shipping. S1 commands are what an org runs to vet and gate an inbound agent. init, log, rotate, and verify work standalone with zero dependencies and zero network calls. eval, scan, and gate need GraphSmith and/or KnoSky installed alongside VIA ID (see below) — that's an intentional seam, not a missing feature.

S2 — developer commands​

init [name]​

node bin/viaid.mjs init "my-agent"

Mints a new AgentID and writes the badge file. Prints the agent_id and the badge's file path. Run once per agent.

log <agent_id> [action] [model]​

node bin/viaid.mjs log via_abc123... "called payments API" claude-sonnet

Appends a hash-chained entry to the badge's log. action defaults to "ran" if omitted; model is optional. Prints the new entry's index.

rotate <agent_id> [reason] [compromisedSince]​

node bin/viaid.mjs rotate via_abc123... routine
node bin/viaid.mjs rotate via_abc123... compromise 2026-07-20T00:00:00.000Z

reason is routine (default) or compromise. For a compromise rotation, pass an ISO timestamp as the third argument for when the key is suspected to have been compromised — verify will flag log entries after that point for the reader to discount. agent_id never changes; only the signing key does, via a pre-committed rotation chain.

eval <agent_id> <targetDir>​

node bin/viaid.mjs eval via_abc123... ./my-agent

Attaches GraphSmith-evaluated capability evidence to the badge — confirmed profiles and explicitly-failed ("downgraded") profiles. Requires GRAPHSMITH_HOME pointed at a GraphSmith installation; throws if GraphSmith isn't available rather than silently skipping.

verify <agent_id>​

node bin/viaid.mjs verify via_abc123...

Prints the verdict (VALID / STALE / REVOKED / UNKNOWN / INVALID), freshness state, assurance tier, key sequence, coverage, scope note, and every individual verification step with its pass/fail status. See Badge schema for exactly what each step checks.

S1 — org commands​

scan <agent_id>​

node bin/viaid.mjs scan via_abc123...

Runs the same verification as verify, framed as an inbound check: reports the verdict and notes VIA ID as the native issuer (pre-cleared lane).

gate <agent_id> [destination]​

node bin/viaid.mjs gate via_abc123... index.js

Issues a KnoSky visitor pass for the agent and checks whether it's authorized to reach destination (defaults to index.js). Prints the decision code and a receipt ID. Requires KNOSKY_HOME pointed at a KnoSky installation.

demo​

node bin/viaid.mjs demo

Runs the entire two-sided flow end-to-end against a small sample agent it generates for you: badge → log → eval → verify (S2), then scan → pass → gate → kill → re-verify (S1). Requires both GRAPHSMITH_HOME and KNOSKY_HOME. Useful as a smoke test after install, or to see a complete integration before wiring your own.

Environment variables​

VariablePurposeRequired for
VIAID_WORKWhere badge files are written/read. Defaults to ./viaid-work/.All commands
GRAPHSMITH_HOMEPath to a GraphSmith installation.eval, demo
KNOSKY_HOMEPath to a KnoSky installation.gate, demo

A note on scope vs. the top-level README​

The package README.md documents the S2 developer flow (init / log / verify / rotate) as the headline usage, since that's what most integrators need first. The full CLI — documented above — also includes eval, scan, gate, and demo. Nothing here is unreleased or aspirational; it's all in bin/viaid.mjs today. If you only need to badge and log your own agent, the four S2 commands are all you'll touch.