> ## Documentation Index > Fetch the complete documentation index at: https://docs.grantex.dev/llms.txt > Use this file to discover all available pages before exploring further. # CLI > Manage agents, grants, audit logs, and more from your terminal. ## Install ```bash theme={null} npm install -g @grantex/cli ``` ## Configure ```bash theme={null} # 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.). ```bash theme={null} grantex --json agents list grantex --json tokens verify grantex --json grants list --status active | jq '.[].id' ``` To disable colored output, set the `NO_COLOR=1` environment variable. ## Commands ### Authorize (Core Flow) ```bash theme={null} # 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 # 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 ```bash theme={null} 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 ```bash theme={null} # Exchange authorization code for a grant token grantex tokens exchange --code --agent-id ag_01ABC... # Exchange with PKCE verifier grantex tokens exchange --code --agent-id ag_01ABC... --code-verifier # Verify a grant token (online check) grantex tokens verify # Refresh a grant token grantex tokens refresh --refresh-token --agent-id ag_01ABC... # Revoke a token by JTI grantex tokens revoke ``` ### Grants ```bash theme={null} 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 --agent-id ag_CHILD... --scopes email:read grantex grants delegate --grant-token --agent-id ag_CHILD... --scopes email:read --expires-in 1h ``` ### Budgets ```bash theme={null} 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 ```bash theme={null} grantex usage current grantex usage history grantex usage history --days 7 ``` ### Events ```bash theme={null} # 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} 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 ```bash theme={null} grantex domains list grantex domains add --domain auth.mycompany.com grantex domains verify dom_01ABC... grantex domains delete dom_01ABC... ``` ### Principal Sessions ```bash theme={null} grantex principal-sessions create --principal-id user@example.com grantex principal-sessions create --principal-id user@example.com --expires-in 1h ``` ### Compliance ```bash theme={null} # 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 ```bash theme={null} grantex anomalies detect grantex anomalies list grantex anomalies list --unacknowledged grantex anomalies acknowledge anom_01XYZ... ``` ### Billing ```bash theme={null} 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 ```bash theme={null} # Show your developer profile and settings grantex me grantex --json me ``` ### Vault (Credential Storage) ```bash theme={null} 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 --service google ``` ### WebAuthn / FIDO2 ```bash theme={null} # 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 ```bash theme={null} 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) ```bash theme={null} 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 ```bash theme={null} # 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 ```bash theme={null} 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 ```bash theme={null} # 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 ```bash theme={null} # 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 --agent-id ag_01ABC... # 5. Verify the token grantex tokens verify # 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: ```bash theme={null} grantex config set --url http://localhost:3001 --key dev-api-key-local ``` ## Requirements * Node.js 18+