CLI

Install

npm install -g @grantex/cli

Configure

# Interactive setup
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 config show

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

JSON Output

All commands support --json for machine-readable output. This is useful for scripting, piping into jq, or when using the CLI from AI coding assistants (Claude Code, Cursor, Codex, etc.).

grantex --json agents list
grantex --json tokens verify <jwt-token>
grantex --json grants list --status active | jq '.[].id'

To disable colored output, set the NO_COLOR=1 environment variable.

Commands

Authorize (Core Flow)

# Start an authorization request
grantex authorize --agent ag_01ABC... --principal user@example.com --scopes email:read,calendar:write

# With PKCE
grantex authorize --agent ag_01ABC... --principal user@example.com --scopes email:read \
  --code-challenge <base64url-sha256-challenge>

# With redirect URI
grantex authorize --agent ag_01ABC... --principal user@example.com --scopes email:read \
  --redirect-uri https://myapp.com/callback

# With custom expiry
grantex authorize --agent ag_01ABC... --principal user@example.com --scopes email:read \
  --expires-in 1h

Agents

grantex agents list
grantex agents register --name travel-booker --description "Books travel" --scopes calendar:read,payments:initiate
grantex agents get ag_01ABC...
grantex agents update ag_01ABC... --name new-name --scopes calendar:read,email:send
grantex agents delete ag_01ABC...

Tokens

# Exchange authorization code for a grant token
grantex tokens exchange --code <auth-code> --agent-id ag_01ABC...

# Exchange with PKCE verifier
grantex tokens exchange --code <auth-code> --agent-id ag_01ABC... --code-verifier <verifier>

# Verify a grant token (online check)
grantex tokens verify <jwt-token>

# Refresh a grant token
grantex tokens refresh --refresh-token <token> --agent-id ag_01ABC...

# Revoke a token by JTI
grantex tokens revoke <jti>

Grants

grantex grants list
grantex grants list --agent ag_01ABC... --status active
grantex grants get grnt_01XYZ...
grantex grants revoke grnt_01XYZ...

# Delegate a grant to a sub-agent
grantex grants delegate --grant-token <parent-jwt> --agent-id ag_CHILD... --scopes email:read
grantex grants delegate --grant-token <parent-jwt> --agent-id ag_CHILD... --scopes email:read --expires-in 1h

Budgets

grantex budgets allocate --grant-id grnt_01XYZ... --amount 100.00
grantex budgets allocate --grant-id grnt_01XYZ... --amount 50 --currency EUR
grantex budgets debit --grant-id grnt_01XYZ... --amount 25.50 --description "API call"
grantex budgets balance grnt_01XYZ...
grantex budgets transactions grnt_01XYZ...

Usage

grantex usage current
grantex usage history
grantex usage history --days 7

Events

# Stream real-time events (Ctrl+C to stop)
grantex events stream

# Filter by event type
grantex events stream --types grant.created,token.issued

# JSON output (one JSON object per line, ideal for piping)
grantex --json events stream

Audit Log

grantex audit list
grantex audit list --agent ag_01ABC... --action payment.initiated --since 2026-01-01
grantex audit list --grant grnt_01XYZ... --principal user@example.com

Webhooks

grantex webhooks list
grantex webhooks create --url https://example.com/hook --events grant.created,grant.revoked
grantex webhooks delete wh_01XYZ...

Supported events: grant.created, grant.revoked, token.issued.

Policies

grantex policies list
grantex policies get pol_01ABC...
grantex policies create --name "Allow Email Bot" --effect allow --agent-id ag_01ABC... --scopes email:read
grantex policies create --name "Block After Hours" --effect deny --time-start 18:00 --time-end 08:00
grantex policies update pol_01ABC... --priority 50
grantex policies delete pol_01ABC...

Domains

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

Principal Sessions

grantex principal-sessions create --principal-id user@example.com
grantex principal-sessions create --principal-id user@example.com --expires-in 1h

Compliance

# Summary stats
grantex compliance summary
grantex compliance summary --since 2026-01-01 --until 2026-02-01

# Export grants
grantex compliance export grants --format json --output grants.json

# Export audit log
grantex compliance export audit --format json --output audit.json

# Evidence pack
grantex compliance evidence-pack --framework soc2 --output evidence.json

Anomaly Detection

grantex anomalies detect
grantex anomalies list
grantex anomalies list --unacknowledged
grantex anomalies acknowledge anom_01XYZ...

Billing

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

Account

# Show your developer profile and settings
grantex me
grantex --json me

Vault (Credential Storage)

grantex vault list
grantex vault list --principal user@example.com --service google
grantex vault get cred_01ABC...
grantex vault store --principal-id user@example.com --service google --access-token ya29... \
  --refresh-token 1//0e... --token-expires-at 2026-04-01T00:00:00Z
grantex vault delete cred_01ABC...
grantex vault exchange --grant-token <jwt> --service google

WebAuthn / FIDO2

# Generate registration challenge
grantex webauthn register-options --principal-id user@example.com

# Verify registration (pass browser attestation response as JSON)
grantex webauthn register-verify --challenge-id ch_01ABC... --response '{"id":"...","response":{...}}' \
  --device-name "MacBook Pro"

# List and delete credentials
grantex webauthn list user@example.com
grantex webauthn delete cred_01ABC...

Verifiable Credentials

grantex credentials list
grantex credentials list --grant-id grnt_01ABC... --status active
grantex credentials get vc_01ABC...

# Verify a VC-JWT
grantex credentials verify --vc-jwt eyJ...

# Verify an SD-JWT presentation
grantex credentials present --sd-jwt eyJ... --nonce abc123

Agent Passports (MPP)

grantex passports issue --agent-id ag_01ABC... --grant-id grnt_01XYZ... \
  --categories "compute,storage" --max-amount 100 --currency USD
grantex passports list --agent-id ag_01ABC...
grantex passports get pp_01ABC...
grantex passports revoke pp_01ABC...

SCIM

# Token management
grantex scim tokens list
grantex scim tokens create --label "Okta Integration"
grantex scim tokens revoke tok_01ABC...

# User provisioning
grantex scim users list
grantex scim users get usr_01ABC...
grantex scim users create --user-name john@example.com --display-name "John Doe" --email john@example.com
grantex scim users update usr_01ABC... --display-name "John D." --active true
grantex scim users replace usr_01ABC... --user-name john@example.com --display-name "John Doe"
grantex scim users delete usr_01ABC...

SSO

grantex sso get
grantex sso configure --issuer-url https://accounts.google.com --client-id CLIENT_ID \
  --client-secret CLIENT_SECRET --redirect-uri https://myapp.com/callback
grantex sso delete
grantex sso login-url my-org
grantex sso callback --code AUTH_CODE --state STATE_PARAM

DPDP Compliance

# Consent notices
grantex dpdp notices create --notice-id privacy-v1 --version 1.0 --title "Privacy Notice" \
  --content "We process your data for..." --purposes '[{"code":"analytics","description":"Usage analytics"}]'

# Consent records
grantex dpdp consent create --grant-id grnt_01ABC... --principal-id user@example.com \
  --purposes '[{"code":"analytics","description":"Usage analytics"}]' \
  --consent-notice-id privacy-v1 --processing-expires-at 2027-01-01T00:00:00Z
grantex dpdp consent get crec_01ABC...
grantex dpdp consent list --principal-id user@example.com
grantex dpdp consent withdraw crec_01ABC... --reason "No longer needed" --revoke-grant

# Data principal rights (DPDP §11)
grantex dpdp principal-records user@example.com
grantex dpdp erasure user@example.com

# Grievances (DPDP §13(6))
grantex dpdp grievances file --principal-id user@example.com --type violation --description "Unauthorized access"
grantex dpdp grievances get grv_01ABC...

# Compliance exports
grantex dpdp exports create --type dpdp-audit --date-from 2026-01-01 --date-to 2026-04-01
grantex dpdp exports get exp_01ABC...

Full Workflow Example

# 1. Configure
grantex config set --url http://localhost:3001 --key sandbox-api-key-local

# 2. Register an agent
grantex agents register --name "Email Reader" --description "Reads emails" --scopes email:read,email:send

# 3. Start authorization (sandbox auto-approves, returns code directly)
grantex authorize --agent ag_01ABC... --principal user@example.com --scopes email:read

# 4. Exchange the code for a token
grantex tokens exchange --code <code-from-step-3> --agent-id ag_01ABC...

# 5. Verify the token
grantex tokens verify <jwt-from-step-4>

# 6. Check audit trail
grantex audit list --agent ag_01ABC...

# 7. Revoke when done
grantex grants revoke grnt_01XYZ...

Local Development

For local development with Docker Compose:

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

Requirements

Node.js 18+

Overview

Service Providers

Framework Integrations

On-Device

Compliance

Agent-to-Agent

Payment Protocol

Testing

CLI

Install

Configure

JSON Output

Commands

Authorize (Core Flow)

Agents

Tokens

Grants

Budgets

Usage

Events

Audit Log

Webhooks

Policies

Domains

Principal Sessions

Compliance

Anomaly Detection

Billing

Account

Vault (Credential Storage)

WebAuthn / FIDO2

Verifiable Credentials

Agent Passports (MPP)

SCIM

SSO

DPDP Compliance

Full Workflow Example

Local Development

Requirements

Overview

Service Providers

Framework Integrations

On-Device

Compliance

Agent-to-Agent

Payment Protocol

CLI

Testing

​Install

​Configure

​JSON Output

​Commands

​Authorize (Core Flow)

​Agents

​Tokens

​Grants

​Budgets

​Usage

​Events

​Audit Log

​Webhooks

​Policies

​Domains

​Principal Sessions

​Compliance

​Anomaly Detection

​Billing

​Account

​Vault (Credential Storage)

​WebAuthn / FIDO2

​Verifiable Credentials

​Agent Passports (MPP)

​SCIM

​SSO

​DPDP Compliance

​Full Workflow Example

​Local Development

​Requirements

Install

Configure

JSON Output

Commands

Authorize (Core Flow)

Agents

Tokens

Grants

Budgets

Usage

Events

Audit Log

Webhooks

Policies

Domains

Principal Sessions

Compliance

Anomaly Detection

Billing

Account

Vault (Credential Storage)

WebAuthn / FIDO2

Verifiable Credentials

Agent Passports (MPP)

SCIM

SSO

DPDP Compliance

Full Workflow Example

Local Development

Requirements