@grantex/cli

Command-line tool for the Grantex delegated authorization protocol.

83 commands covering the full Grantex API — agents, grants, tokens, policies, budgets, audit, compliance, credentials, and more. All commands support --json for machine-readable output.

Homepage | Docs | CLI Docs | GitHub

Install

npm install -g @grantex/cli

Configure

grantex config set --url https://grantex-auth-dd4mtrt2gq-uc.a.run.app --key YOUR_API_KEY

# Or use environment variables
export GRANTEX_URL=https://grantex-auth-dd4mtrt2gq-uc.a.run.app
export GRANTEX_KEY=YOUR_API_KEY

# Verify your setup
grantex me

Config is saved to ~/.grantex/config.json. Environment variables override the config file.

JSON Output

All commands support --json for machine-readable output — ideal for scripting, jq, and AI coding assistants (Claude Code, Cursor, Codex).

grantex --json agents list | jq '.[0].agentId'
grantex --json tokens verify <jwt> | jq '.valid'

Set NO_COLOR=1 to disable colored output.

Commands

Core Flow

# 1. Register an agent
grantex agents register --name "My Bot" --description "Reads email" --scopes email:read

# 2. Start authorization
grantex authorize --agent ag_... --principal [email protected] --scopes email:read

# 3. Exchange code for token
grantex tokens exchange --code <code> --agent-id ag_...

# 4. Verify the token
grantex tokens verify <jwt>

# 5. Refresh when needed
grantex tokens refresh --refresh-token <token> --agent-id ag_...

# 6. Revoke when done
grantex grants revoke grnt_...

Agents

grantex agents list
grantex agents register --name bot --description "..." --scopes email:read,calendar:write
grantex agents get ag_...
grantex agents update ag_... --name new-name --scopes email:read
grantex agents delete ag_...

Grants

grantex grants list [--agent ag_... --status active]
grantex grants get grnt_...
grantex grants revoke grnt_...
grantex grants delegate --grant-token <jwt> --agent-id ag_child... --scopes email:read

Tokens

grantex tokens exchange --code <code> --agent-id ag_...
grantex tokens verify <jwt>
grantex tokens refresh --refresh-token <token> --agent-id ag_...
grantex tokens revoke <jti>

Authorize

grantex authorize --agent ag_... --principal [email protected] --scopes email:read
grantex authorize --agent ag_... --principal [email protected] --scopes email:read \
  --code-challenge <S256-challenge> --redirect-uri https://app.com/callback

Audit

grantex audit list [--agent ag_... --grant grnt_... --action email.read --since 2026-01-01]
grantex audit get alog_...
grantex audit log --agent-id ag_... --agent-did did:grantex:ag_... --grant-id grnt_... \
  --principal-id [email protected] --action email.read --status success

Policies

grantex policies list
grantex policies get pol_...
grantex policies create --name "Allow Bot" --effect allow --agent-id ag_... --scopes email:read
grantex policies update pol_... --priority 50
grantex policies delete pol_...

Budgets

grantex budgets allocate --grant-id grnt_... --amount 100 [--currency USD]
grantex budgets debit --grant-id grnt_... --amount 25.50 --description "API call"
grantex budgets balance grnt_...
grantex budgets transactions grnt_...

Usage

grantex usage current
grantex usage history [--days 7]

Webhooks

grantex webhooks list
grantex webhooks create --url https://example.com/hook --events grant.created,token.issued
grantex webhooks delete wh_...

Events

grantex events stream [--types grant.created,token.issued]
grantex --json events stream  # One JSON object per line

Domains

grantex domains list
grantex domains add --domain auth.mycompany.com
grantex domains verify dom_...
grantex domains delete dom_...

Vault (Credential Storage)

grantex vault list [--principal [email protected] --service google]
grantex vault get cred_...
grantex vault store --principal-id [email protected] --service google --access-token ya29...
grantex vault delete cred_...
grantex vault exchange --grant-token <jwt> --service google

WebAuthn / FIDO2

grantex webauthn register-options --principal-id [email protected]
grantex webauthn register-verify --challenge-id ch_... --response '{"id":"..."}' --device-name "MacBook"
grantex webauthn list [email protected]
grantex webauthn delete cred_...

Verifiable Credentials

grantex credentials list [--grant-id grnt_... --status active]
grantex credentials get vc_...
grantex credentials verify --vc-jwt eyJ...
grantex credentials present --sd-jwt eyJ... --nonce abc123

Agent Passports (MPP)

grantex passports issue --agent-id ag_... --grant-id grnt_... --categories "compute,storage" --max-amount 100
grantex passports list [--agent-id ag_...]
grantex passports get pp_...
grantex passports revoke pp_...

Principal Sessions

grantex principal-sessions create --principal-id [email protected] [--expires-in 1h]

Account

grantex me

Compliance

grantex compliance summary [--since 2026-01-01 --until 2026-02-01]
grantex compliance export grants --format json --output grants.json
grantex compliance export audit --format json --output audit.json
grantex compliance evidence-pack --framework soc2 --output evidence.json

Anomalies

grantex anomalies detect
grantex anomalies list [--unacknowledged]
grantex anomalies acknowledge anom_...

Billing

grantex billing status
grantex billing checkout pro --success-url https://app.com/ok --cancel-url https://app.com/cancel
grantex billing portal --return-url https://app.com/settings

SCIM

grantex scim tokens list | create --label "Okta" | revoke tok_...
grantex scim users list | get usr_... | create --user-name [email protected] | update usr_... | delete usr_...

SSO

grantex sso get | configure --issuer-url ... --client-id ... | delete
grantex sso login-url my-org
grantex sso callback --code CODE --state STATE

Local Development

grantex config set --url http://localhost:3001 --key dev-api-key-local

Requirements

• Node.js 18+

License

Apache 2.0