CLI Reference

The kanoniv-auth CLI provides the full Kanoniv Auth workflow from the terminal: generate keys, delegate authority, verify scopes, sign execution envelopes, and manage agents.

Install

pip install kanoniv-auth

Two entry points are installed:

Command	Purpose
kanoniv-auth	Local delegation, verification, signing, audit
kt	Cloud commands - agent registry, delegation, provenance (requires pip install kanoniv-auth[cloud])

Commands

Key Management

kanoniv-auth init

Generate a root key pair.

kanoniv-auth init
kanoniv-auth init --output /path/to/root.key
kanoniv-auth init --force  # Overwrite existing

Option	Default	Description
--output, -o	~/.kanoniv/root.key	Output path
--force	false	Overwrite existing key

WARNING

The root key file contains your private key. Treat it like an SSH key. Do not commit it to version control or share it.

Delegation

kanoniv-auth delegate

Issue a delegation token.

kanoniv-auth delegate --scopes code.edit,test.run --ttl 4h --name my-agent
kanoniv-auth delegate -s deploy.staging -t 1h -n ci-agent --export
kanoniv-auth delegate -s resolve --parent "$PARENT_TOKEN"  # Sub-delegation

Option	Default	Description
--scopes, -s	(required)	Comma-separated scopes
--ttl, -t	no expiry	TTL string (4h, 30m, 1d)
--name, -n	none	Persistent agent name (same name produces same DID across sessions)
--key, -k	~/.kanoniv/root.key	Root key file
--parent	none	Parent token for sub-delegation
--export	false	Output as export KANONIV_TOKEN=... (eval-able)
--dry-run	false	Preview without signing

The token is saved to ~/.kanoniv/tokens/ automatically. The most recent token is symlinked as latest.token.

kanoniv-auth revoke

Revoke a delegation.

kanoniv-auth revoke --token "$TOKEN"
kanoniv-auth revoke --service https://auth.kanoniv.com --delegation-id abc123

Option	Default	Description
--token, -t	none	Token string to revoke locally (deletes from ~/.kanoniv/tokens/)
--service	none	Delegation service URL for remote revocation
--delegation-id	none	Delegation ID to revoke on service (used with --service)

Verification

kanoniv-auth verify

Check scope authorization. Verification is offline - no server calls, no network required.

kanoniv-auth verify --scope code.edit
kanoniv-auth verify --scope deploy.prod --token "$TOKEN"
kanoniv-auth verify -s git.push.main --agent my-agent

Option	Default	Description
--scope, -s	(required)	Scope to verify
--token, -t	$KANONIV_TOKEN or latest.token	Token
--agent, -a	none	Load token by agent name

Exit codes: 0 = PASS, 1 = DENIED/EXPIRED.

Output on success:

VERIFIED
  Agent:   did:agent:5e06a3...
  Root:    did:agent:a1b2c3...
  Scopes:  ['code.edit', 'test.run']
  Expires: 3.9h remaining
  Chain:   1 link(s)

kanoniv-auth sign

Sign an execution envelope.

kanoniv-auth sign --action deploy.staging --target app-v2.3.1
kanoniv-auth sign -a code.edit --target src/main.py --result success

Option	Default	Description
--action, -a	(required)	Action performed
--token, -t	latest token	Token
--agent	none	Agent name
--target	""	Target of action
--result	success	Outcome (success/failure/partial)

Outputs a base64url-encoded signed envelope.

kanoniv-auth exec

Verify, execute, and sign in one command. If the scope check fails, the command never runs.

kanoniv-auth exec --scope deploy.staging -- ./deploy.sh staging
kanoniv-auth exec -s test.run -- npm test
kanoniv-auth exec -s build --agent ci-agent -- make release

Option	Default	Description
--scope, -s	(required)	Required scope
--token, -t	latest token	Token
--agent, -a	none	Agent name

The exit code matches the executed command. The result is signed automatically and logged to the audit trail.

INFO

exec is the "sudo" experience. Verify before execution, sign after. If verification fails, the command never runs. If it succeeds, the result is signed and logged.

Status and Audit

kanoniv-auth status

Check current delegation status.

kanoniv-auth status
kanoniv-auth status --agent my-agent

Option	Default	Description
--token, -t	latest token	Token
--agent, -a	none	Load token by agent name

Output when active:

ACTIVE
  Agent:  my-agent
  DID:    did:agent:5e06a3...
  Scopes: code.edit, test.run
  TTL:    1h 42m

Output when expired:

EXPIRED
  Agent:  my-agent
  Died:   23m ago

  Re-delegate:
    kanoniv-auth delegate --name my-agent --scopes code.edit,test.run --ttl 4h

kanoniv-auth whoami

Show identity behind a token.

kanoniv-auth whoami
kanoniv-auth whoami --token "$TOKEN"

Option	Default	Description
--token, -t	latest token	Token
--agent, -a	none	Load token by agent name

Shows agent name, DID, root DID, scopes, TTL remaining, chain depth, and whether the embedded key supports sub-delegation and signing.

kanoniv-auth audit TOKEN_OR_ENVELOPE

Pretty-print a delegation chain or execution envelope.

kanoniv-auth audit "$TOKEN"

Takes a base64url-encoded token or envelope as a positional argument. Shows the full delegation chain with each link's issuer, delegate, and scopes.

kanoniv-auth audit-log

View the local audit trail.

kanoniv-auth audit-log
kanoniv-auth audit-log --agent my-agent --action verify --since 2026-03-22 --limit 20

Option	Default	Description
--agent, -a	all	Filter by agent name
--action	all	Filter: delegate, verify, sign, exec
--since	all	ISO date filter (e.g. 2026-03-22)
--limit, -n	50	Max entries

kanoniv-auth tokens

List all saved delegation tokens.

kanoniv-auth tokens

Shows each token's file path, agent DID, scopes, TTL remaining, and active/expired status.

Agent Management

kanoniv-auth agents list

List all registered agents (local persistent identities).

kanoniv-auth agents list

kanoniv-auth agents show NAME

Show agent details - full DID and public key hex.

kanoniv-auth agents show my-agent

kanoniv-auth agents remove NAME

Remove a registered agent. Prompts for confirmation.

kanoniv-auth agents remove my-agent

kanoniv-auth agents rename OLD NEW

Rename agent. Keeps the same DID and key material.

kanoniv-auth agents rename old-name new-name

Installation

kanoniv-auth install-skill

Install five Claude Code skills: /delegate, /scope, /ttl, /status, /audit.

kanoniv-auth install-skill

Skills are installed to ~/.claude/skills/. Each skill includes a SKILL.md and supporting scripts for PreToolUse/PostToolUse hooks.

kanoniv-auth install-hook

Install git pre-push hook for scope enforcement.

kanoniv-auth install-hook
kanoniv-auth install-hook --repo /path/to/repo --force

Option	Default	Description
--repo, -r	. (current directory)	Path to git repository
--force	false	Overwrite existing pre-push hook

The hook verifies git.push.{repo}.{branch} scope before allowing pushes. Remove with rm .git/hooks/pre-push.

Cloud Commands (kt)

The kt command provides access to the Observatory cloud API. Requires pip install kanoniv-auth[cloud].

kt --help
kt --url https://auth.kanoniv.com --api-key kt_live_... agents

Option	Default	Description
--url	https://trust.kanoniv.com	Trust API URL (also: KT_URL env var)
--api-key	~/.kanoniv/cloud.key	API key (also: KT_API_KEY env var)

Command	Purpose
kt signup	Create account (saves API key to ~/.kanoniv/cloud.key)
kt login	Log in and save API key
kt me	Show tenant info and usage
kt register NAME -c CAPS	Register an agent with capabilities
kt agents	List all agents with reputation scores
kt agent NAME	Agent details as JSON
kt delete NAME	Delete agent and revoke delegations
kt delegate FROM TO -s SCOPES	Grant delegation between agents
kt delegations [AGENT]	List active delegations
kt revoke ID	Revoke a delegation
kt action AGENT ACTION	Record a provenance entry (enforced)
kt log	Show recent provenance log
kt memorize AGENT TITLE	Save a memory entry
kt memories	List memory entries
kt feedback DID ACTION RESULT	Submit feedback (success/failure/partial)
kt demo	Run a live demo scenario

Cloud commands are also accessible as subcommands of kanoniv-auth cloud:

kanoniv-auth cloud agents
kanoniv-auth cloud delegate coordinator sdr-agent -s resolve,search

Token Resolution Order

When you run a CLI command without --token, the CLI resolves the token in this order:

1. --token flag (explicit token string)
2. --agent flag (loads the most recent token for that named agent from ~/.kanoniv/tokens/)
3. KANONIV_TOKEN environment variable
4. ~/.kanoniv/tokens/latest.token (the most recently issued token)

Environment Variables

Variable	Purpose
KANONIV_TOKEN	Default delegation token (used by verify, sign, exec)
KANONIV_ROOT_KEY	Path to root key file (default: ~/.kanoniv/root.key)
KT_API_KEY	API key for cloud commands
KT_URL	Observatory API URL for cloud commands

File Locations

Path	Purpose
~/.kanoniv/root.key	Root key pair (JSON, chmod 600)
~/.kanoniv/tokens/latest.token	Most recent delegation token
~/.kanoniv/tokens/	All saved delegation tokens
~/.kanoniv/cloud.key	Observatory API key (saved by kt login)
~/.kanoniv/audit.log	Append-only local audit trail
~/.claude/skills/	Claude Code skills (installed by install-skill)
.git/hooks/pre-push	Git pre-push scope enforcement (installed by install-hook)

Next Steps

• Getting Started - Quickstart walkthrough
• Claude Code Skills - Five skills with scope enforcement
• wrap-mcp - MCP proxy for any server
• Kanoniv Auth - Back to overview