CLI - Grantex

Install

npm install -g @grantex/cli@0.4.2

Node.js 22.12+ is required. This release uses SDK 0.8 enforcement: expected audience, trusted amounts for capped calls and default online revocation. See migration. An agent-controlled CLI preflight does not replace enforcement at the service that owns the side effect.

Configure

# Interactive setup
grantex config set --url https://api.grantex.dev --key YOUR_API_KEY

# Or use environment variables
export GRANTEX_URL=https://api.grantex.dev
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.

Install skills for an agent CLI

The CLI bundles use-grantex-cli and integrate-grantex as portable Agent Skills:

# OpenClaw workspace
grantex agent install --target openclaw

# Hermes Agent
grantex agent install --target hermes

# Project-local .agents/skills
grantex agent install --target portable

# Any custom skill root
grantex agent install --dir /path/to/skills

See Agent CLIs & Skills for discovery paths, activation checks, and security boundaries.

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. Denied and invalid checks return a non-zero exit status in JSON mode as well as text mode.

Secret-safe token input

Avoid putting grant tokens in shell history or process arguments:

grantex verify --env GRANTEX_GRANT_TOKEN --json
grantex --json tokens verify --env GRANTEX_GRANT_TOKEN
grantex --json enforce test --token-env GRANTEX_GRANT_TOKEN \
  --connector salesforce --tool create_lead

The verification commands also accept --file and --stdin. enforce test accepts --token-file and --token-stdin.

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 register --name callback-agent --description "Uses an authorization callback" --scopes records:read \
  --redirect-uri https://client.example/grants/callback
grantex agents get ag_01ABC...
grantex agents update ag_01ABC... --name new-name --scopes calendar:read,email:send
grantex agents update ag_01ABC... --redirect-uri https://client.example/grants/callback
grantex agents update ag_01ABC... --clear-redirect-uris
grantex agents delete ag_01ABC...

Repeat --redirect-uri for multiple callbacks. On update, these values replace the complete list. Omitting the option preserves existing callbacks, while --clear-redirect-uris removes all of them. Live authorization requires an exact match to a registered HTTPS URI.

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 Records

These commands keep the records described in DPDP Compliance; they help evidence DPDP Act obligations and are not legal advice.

# Consent notices (DPDP s.5, DPDP Rules 2025 r.3). Use --notice-version;
# --version anywhere on the command line prints the CLI version.
grantex dpdp notices create --notice-id privacy-v1 --notice-version 1.0 --title "Privacy Notice"   --content "We process your data for..." --purposes '[{"code":"analytics","description":"Usage analytics"}]'
grantex dpdp notices list
grantex dpdp notices get privacy-v1

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

# Data principal rights: access (DPDP s.11) and erasure (s.12)
grantex dpdp principal-records user@example.com
grantex dpdp erasure user@example.com
grantex dpdp erasure status ER-2026-...

# Grievances (DPDP s.13)
grantex dpdp grievances file --principal-id user@example.com --type unauthorized-processing --description "Data used beyond the consented purpose"
grantex dpdp grievances list --status submitted
grantex dpdp grievances get grv_01ABC...
grantex dpdp grievances update grv_01ABC... --status resolved --resolution "Processing stopped"

# Compliance exports (JSON only; a bare YYYY-MM-DD means 00:00Z, so give an
# end-of-day time to include the last day)
grantex dpdp exports create --type dpdp-audit --date-from 2026-01-01 --date-to 2026-03-31T23:59:59Z
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 22.12+

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

​Install

​Configure

​Install skills for an agent CLI

​JSON Output

​Secret-safe token input

​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 Records

​Full Workflow Example

​Local Development

​Requirements

​Ownership