zcap-cli

A utility CLI for working with zcaps (Authorization Capabilities).

Install

npm install
npm link  # optional, to use `zcap` globally

Init

Create an initial app identity for use by the other commands.

Your CLI did:key identity is stored in ~/.zcap-cli/config.json. Generate an initial identity using:

zcap init

Key Management

All commands that require a signing key support two modes:

1. Config-based (default): Uses the key stored in ~/.zcap-cli/config.json (created by zcap init).
2. Seed-based: Pass --seed-multibase with a base58btc-encoded seed (z-prefix) to derive the signing key on the fly, without needing a local config.

Create

Create a root zcap for invocation.

zcap create https://example.com/resource \
  --controller did:key:YOUR_IDENTITY \
  --ttl=3600 \
  --output=-

With a seed instead of config:

zcap create https://example.com/resource \
  --controller did:key:YOUR_IDENTITY \
  --seed-multibase=zYOUR_SEED \
  --ttl=3600 \
  --output=-

Option	Required	Default	Description
<url>	yes		Resource URL
--controller	yes		Controller DID
--ttl	no	3600	Time to live in seconds
--seed-multibase	no		Multibase seed for the controller key
--output	no	capability.json	Output file or - for stdout

Delegate

Delegate an existing capability to another DID.

zcap delegate ./capability.json \
  --to did:key:DELEGATEE \
  --invocation-target='https://example.com/resource/scoped' \
  --allowed-actions=read,write \
  --ttl=3600 \
  --output=-

Option	Required	Default	Description
<parent>	yes		Path to parent capability JSON file
--to	yes		DID of the delegatee
--invocation-target	no	parent's target	Invocation target URL override
--allowed-actions	no	read	Comma-separated allowed actions
--ttl	no	parent's expiration	Time to live in seconds
--seed-multibase	no		Multibase seed for the signing key
--output	no	delegated.json	Output file or - for stdout

Delegate Root

Delegate a root capability directly, without needing a parent capability file. The root capability URN is derived from the invocation target URL.

zcap delegate-root \
  --to did:key:DELEGATEE \
  --invocation-target='https://example.com/resource/scoped' \
  --allowed-actions=write \
  --ttl=31536000 \
  --output=-

With explicit controller and seed:

zcap delegate-root \
  --to did:key:DELEGATEE \
  --invocation-target='https://example.com/resource/scoped' \
  --allowed-actions=write \
  --ttl=31536000 \
  --root-controller=${ROOT_CONTROLLER} \
  --root-seed-multibase=${SEED_MULTIBASE} \
  --output=-

Option	Required	Default	Description
--to	yes		DID of the delegatee
--invocation-target	yes		Resource URL the capability targets
--allowed-actions	no	read	Comma-separated allowed actions
--ttl	no	3600	Time to live in seconds
--root-controller	no	config default key	DID of the root controller
--root-seed-multibase	no		Multibase seed for the root controller key
--output	no	delegated-root.json	Output file or - for stdout

Invoke

Invoke an operation on a zcap-protected endpoint.

zcap invoke https://example.com/resource \
  -z ./capability.json \
  -X POST \
  -a write \
  -d '{"hello": "world"}'

Option	Required	Default	Description
<url>	yes		Target URL
-z, --capability	yes		Path to capability JSON file
-X, --method	no	GET	HTTP method
-a, --action	no	read	Capability action
-d, --body	no		JSON request body (string or @file)
--seed-multibase	no		Multibase seed for the signing key