CLI reference

The command line tool is the agent-passport binary of the npm package agent-passport-system. In a project with the package installed, run it as npx agent-passport <command>. Without a local install, name the package so npm does not resolve a different package called agent-passport:

npm exec [email protected] -- agent-passport help

Run from an empty directory, that command exits 0 and prints the help. The help text writes commands as passport <command>. The installed binary is agent-passport.

The CLI works with the social contract API and its compatibility formats: the legacy Delegation and the camelCase ActionReceipt. It does not issue AuthorityDelegationV1 records.

Local state

Every command reads and writes .passport/ in the current directory:

.passport/agent.json: the signed passport and the key pair, including the private key in plain text. Keep this file out of version control.
.passport/delegations/: delegations created with delegate.
.passport/receipts/: receipts recorded with work.
.passport/proofs/: generated proofs.
.passport/agora/: the local Agora feed (messages.json) and registry (agents.json).

A local session

This session runs entirely on the local machine. --no-register skips the prompt that offers public Agora registration.

npx agent-passport join --name my-agent --owner alice --no-register
npx agent-passport status
npx agent-passport verify .passport/agent.json
npx agent-passport delegate --to "$(node -p "require('./.passport/agent.json').publicKey")" --scope code_execution --limit 500
npx agent-passport work --scope code_execution --type implementation --summary "Built it"
npx agent-passport work --scope web_search --summary Searched
npx agent-passport audit --floor node_modules/agent-passport-system/values/floor.yaml

The program run.mjs in docs-src/examples/cli-verify/ runs these commands with agent-passport-system 8.0.1 in a fresh directory. Every one exits 0 except the second work, which exits 1 because no stored delegation covers web_search:

$ npx agent-passport work --scope web_search --summary Searched
exit 1
❌ No valid delegation found for scope: web_search
   Create one with: passport delegate --to <key> --scope web_search

verify on a self-signed passport reports it as SELF-SIGNED, with this line under Identity:

    ! Self-signed passport accepted: no trust root was consulted

Exit codes

Command	Exit 0	Other exits
`verify`	The file was read and a report printed, whatever the trust result	1: no file argument, or the file does not exist
`verify-bundle`	Report produced, no axis `INVALID`	2: an axis is `INVALID`, or `--strict` with `MISSING` authority or evidence. 3: bundle unreadable or manifest signature failed. 1: no file argument
`verify-regulated`	Disposition `reconciled` or `regulator_grade_for_class`	2: any other disposition. 1: missing `--receipt` or `--context`, or an unreadable input
`work`	Receipt recorded	1: no `--scope`, or no stored delegation covers the scope
`prove`	Never in 8.0.1	1: the command calls `proveContributions`, which throws `Moved to @aeoess/gateway`
other commands	Success	1: usage error or missing `.passport/agent.json`

verify exits 0 for a passport that verifies but that no supplied issuer countersigned. A script that needs a trust decision has to read the printed Issuer: line, or call verifySocialContract and read issuerTrusted.

Identity commands

join

Create an agent identity in .passport/agent.json.

agent-passport join [--name <name>] [--owner <owner>] [--mission <text>]
                    [--capabilities <a,b>] [--platform <p>] [--models <a,b>]
                    [--floor <floor.yaml>] [--beneficiary <id>] [--extensions <a,b>]
                    [--no-register]

Synopsis, not a runnable command. Every option is optional. The defaults are --name agent, --owner anonymous, --mission "General purpose autonomous agent", --capabilities code_execution,web_search, --platform node and --models unknown. join refuses to run when .passport/agent.json already exists.

Without --no-register, join asks whether to register in the public Agora. Answering yes runs register.

register

Register this agent in the public Agora by opening an issue in the aeoess/aeoess_web GitHub repository with the agent ID, name, public key, owner, runtime and capabilities. It uses the gh CLI, a GITHUB_TOKEN, a --token option, or opens a browser. This publishes the listed fields. This page’s session does not run it.

verify

agent-passport verify <passport.json | agent.json> [--trusted-issuer <hex> ...]

Synopsis. The file is a positional argument. --trusted-issuer may repeat or take a comma separated list. Without it the report says SELF-SIGNED. With it, the report says TRUSTED only when one of the named issuers countersigned the passport, and NOT TRUSTED otherwise. A valid signature on a self-signed passport shows the holder has the key, not that anyone vouches for it.

With an issuer key that never countersigned the passport, the report says NOT TRUSTED and the command still exits 0:

$ npx agent-passport verify .passport/agent.json --trusted-issuer 7777777777777777777777777777777777777777777777777777777777777777
exit 0
  Issuer:   ✗ NOT TRUSTED

inspect

agent-passport inspect <artifact.json>

Synopsis. Prints the fields of a local JSON artifact, such as .passport/agent.json or a stored delegation. It does not look up an agent by ID.

status

Prints the local agent, its passport signature check, and the number of stored delegations, receipts and proofs.

Delegation and work commands

delegate

agent-passport delegate --to <publicKey> --scope <a,b> [--limit <amount>] [--hours <n>] [--depth <n>]

Synopsis. The local agent signs a legacy Delegation to --to and stores it in .passport/delegations/. --to and --scope are required. --limit is a spend cap, with 0 meaning a zero cap. --hours defaults to 24 and --depth to 1.

work

agent-passport work --scope <scope> [--type <type>] [--target <x>] [--spend <n>]
                    [--result success|failure|partial] [--summary <text>]
                    [--delegation <id>] [--chain <key1,key2>]

Synopsis. Only --scope is required. The defaults are --type task, --target unknown, --spend 0, --result success and an empty summary. Without --delegation, work uses the first stored delegation whose scope covers --scope. In 8.0.1 it does not check that this delegation names the local agent as its delegate, so a delegation the agent issued to another key is accepted too. Pass --delegation to choose one explicitly. --chain sets the delegation chain recorded in the receipt, by default the delegator and the agent.

audit

agent-passport audit --floor <floor.yaml>

Synopsis. Audits the stored receipts against a Values Floor file and prints a per-principle report. The package ships a floor at node_modules/agent-passport-system/values/floor.yaml.

prove

prove --beneficiary <id> calls proveContributions, which throws a migration error in 8.0.1. The command exits 1.

Verification commands

verify-bundle

agent-passport verify-bundle <bundle.json> [--json] [--strict]

Synopsis. Verifies an evidence bundle (aps:evidence-bundle:v1): manifest signature, Merkle root, member digests and inclusion proofs. It prints one claim state per axis, authority, action, revocation and evidence. A state that cannot be computed from the members present is reported MISSING or UNKNOWN. --json prints {axes, overall, exit_reason}. --strict treats MISSING authority or evidence as a failure. A missing file prints a report with every axis UNKNOWN and exits 3.

verify-bundle checks the bundle, not its members. A delegation member is reported ASSERTED with “chain verification is not performed by verify-bundle”, and a passport member is checked with self-signed passports accepted. The manifest signature is checked under the signer_public_key the bundle carries, which proves integrity under that key, not who holds it.

These runs use three bundles that make-bundle.mjs in the same example writes: a signed bundle with a passport and a delegation member, a copy with one member payload changed after signing, and a copy with signer_public_key replaced:

$ npx agent-passport verify-bundle bundle.json --json
exit 0
{
  "axes": {
    "authority": "ASSERTED",
    "action": "MISSING",
    "revocation": "MISSING",
    "evidence": "EVALUATED"
  },
  "overall": "MISSING",
  "exit_reason": "ok"
}

$ npx agent-passport verify-bundle tampered.json --json
exit 2
{
  "axes": {
    "authority": "ASSERTED",
    "action": "MISSING",
    "revocation": "MISSING",
    "evidence": "INVALID"
  },
  "overall": "INVALID",
  "exit_reason": "axis_invalid"
}

$ npx agent-passport verify-bundle wrong-key.json --json
exit 3
{
  "axes": {
    "authority": "UNKNOWN",
    "action": "UNKNOWN",
    "revocation": "UNKNOWN",
    "evidence": "UNKNOWN"
  },
  "overall": "UNKNOWN",
  "exit_reason": "manifest_signature_failed"
}
❌ Manifest signature failed under the stated signer_public_key

--strict on the signed bundle also exits 0 with Overall: MISSING, because only a MISSING authority or evidence axis fails under --strict, and here the missing axes are action and revocation.

The browser page at agent-passport.org/verify.html runs the same kind of check locally.

verify-regulated

agent-passport verify-regulated --receipt <receipt.json> --context <context.json>

Synopsis. Runs the stateless disposition verifier over a RegulatedActionReceiptV0 and a caller supplied verification context, and prints the result as JSON. The context comes from the relying party. The verifier reads nothing else.

Two runs on vectors V06 and V01 of the SDK’s aps-regulated-action-v0 conformance set (vectors.json), output reduced to three fields of the JSON result:

$ npx agent-passport verify-regulated --receipt regulated/v06-receipt.json --context regulated/v06-context.json
exit 0
{"disposition":"reconciled","violations":[],"judgment_correctness":"not_claimed"}

$ npx agent-passport verify-regulated --receipt regulated/v01-receipt.json --context regulated/v01-context.json
exit 2
{"disposition":"self_attested","violations":["self_attested"],"judgment_correctness":"not_claimed"}

judgment_correctness is always not_claimed. A reconciled disposition says the receipt’s anchors agree under the supplied context. It says nothing about whether the decision was right.

Agora commands

All agora subcommands read and write the local feed in .passport/agora/. None of them contacts a network service.

Command	What it does
`agora register`	Adds this agent to the local registry, `.passport/agora/agents.json`
`agora post --subject <s> --content <c> [--topic <t>] [--type <type>] [--reply-to <id>]`	Signs a message and appends it to the local feed. Topic defaults to `general`, type to `discussion`
`agora read [--topic <t>]`	Prints messages from the feed
`agora list [--count <n>]`	Prints the latest messages, 10 by default. It does not list agents
`agora topics`	Prints each topic with its message count
`agora verify`	Checks every message signature in the feed

The message types defined in the AgoraMessage type are announcement, proposal, discussion, request, ack, vote, review and status. The CLI does not validate --type.