> ## 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.

# grantex enforce

> Dry-run scope enforcement from the command line. Test whether a grant token permits a specific tool call before deploying.

## Overview

`grantex enforce test` lets you dry-run scope enforcement against a real grant token without writing any code. Pass a token, connector, and tool name to see whether the call would be allowed or denied, and why.

```bash theme={null}
npm install -g @grantex/cli
```

Prefer a secret-safe token source for agent automation:

```bash theme={null}
grantex --json enforce test \
  --token-env GRANTEX_GRANT_TOKEN \
  --connector salesforce \
  --tool create_lead
```

Use `--token-file <path>` or `--token-stdin` as alternatives. Allowed decisions exit `0`; denied or invalid decisions exit non-zero, including with `--json`.

***

## grantex enforce test

Test whether a grant token permits a specific tool call.

```bash theme={null}
grantex enforce test --token <jwt> --connector <connector> --tool <tool>
```

### Allowed Example

```bash theme={null}
grantex enforce test \
  --token "eyJhbGciOiJSUzI1NiIs..." \
  --connector salesforce \
  --tool create_lead
```

```
  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         ALLOWED
  Connector      salesforce
  Tool           create_lead
  Permission     write (from manifest)

  Token Scopes
  └ tool:salesforce:write:*

  Grant ID       grnt_01HXYZ
  Agent DID      did:grantex:ag_01HXYZ

  ─────────────────────────────────────────────
```

### Denied Example

```bash theme={null}
grantex enforce test \
  --token "eyJhbGciOiJSUzI1NiIs..." \
  --connector salesforce \
  --tool delete_contact
```

```
  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         DENIED
  Connector      salesforce
  Tool           delete_contact
  Permission     delete (from manifest)

  Token Scopes
  └ tool:salesforce:write:*

  Reason         write scope does not permit delete operations

  Grant ID       grnt_01HXYZ
  Agent DID      did:grantex:ag_01HXYZ

  ─────────────────────────────────────────────
```

***

## Capped Scopes

Use the `--amount` flag to test enforcement against capped scopes. From the
next SDK release, a capped scope denies a test without `--amount`
(`amount_missing`):

```bash theme={null}
grantex enforce test \
  --token "eyJ..." \
  --connector stripe \
  --tool create_payment_intent \
  --amount 750
```

```
  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         DENIED
  Connector      stripe
  Tool           create_payment_intent
  Permission     write (from manifest)

  Token Scopes
  └ tool:stripe:write:*:capped:500

  Reason         amount 750 exceeds cap of 500

  ─────────────────────────────────────────────
```

When within the cap:

```bash theme={null}
grantex enforce test \
  --token "eyJ..." \
  --connector stripe \
  --tool create_payment_intent \
  --amount 200
```

```
  Scope Enforcement Test
  ───────────────────────────────────────────

  Result         ALLOWED
  Connector      stripe
  Tool           create_payment_intent
  Permission     write (from manifest)
  Amount         200 (within cap of 500)

  Token Scopes
  └ tool:stripe:write:*:capped:500

  ─────────────────────────────────────────────
```

***

## Grant Token Audience

<Warning>
  Available in `@grantex/cli@0.4.0` with SDK 0.8.0. Node.js 22.12+
  is required; audience binding and default online revocation are breaking changes.
</Warning>

A grant token requested with an `audience` carries it in the `aud` claim, and
`enforce()` denies it unless the relying party expects that audience (see
[Grant token audience](/sdks/typescript/enforce#grant-token-audience)). Pass
the audience your service is issued tokens for with `--audience`:

```bash theme={null}
grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool create_lead \
  --audience https://api.merchant.example
```

Without `--audience`, a token that carries `aud` is reported as denied with
`token_invalid` / `audience_unconfigured`; a token whose `aud` does not contain
the `--audience` value is denied with `token_invalid` / `audience_mismatch`.
`--audience-check off` ignores `aud`, as earlier releases did:

```bash theme={null}
grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool create_lead \
  --audience-check off
```

`--audience-check` takes `on` (the default) or `off`; any other value is
refused. `--audience` cannot be empty or combined with `--audience-check off`,
and both options are refused when the installed `@grantex/sdk` does not check
the audience, instead of being ignored.

***

## JSON Output

Use `--json` for machine-readable output, useful for scripting and CI pipelines:

```bash theme={null}
grantex enforce test \
  --token "eyJ..." \
  --connector salesforce \
  --tool delete_contact \
  --json
```

```json theme={null}
{
  "allowed": false,
  "connector": "salesforce",
  "tool": "delete_contact",
  "permission": "delete",
  "scopes": ["tool:salesforce:write:*"],
  "reason": "write scope does not permit delete operations",
  "grantId": "grnt_01HXYZ",
  "agentDid": "did:grantex:ag_01HXYZ"
}
```

Allowed result:

```json theme={null}
{
  "allowed": true,
  "connector": "salesforce",
  "tool": "create_lead",
  "permission": "write",
  "scopes": ["tool:salesforce:write:*"],
  "reason": "",
  "grantId": "grnt_01HXYZ",
  "agentDid": "did:grantex:ag_01HXYZ"
}
```

***

## Options

| Flag | Description |
| - | - |
| `--token <jwt>` | The grant token to test against (required) |
| `--connector <name>` | The connector name (required) |
| `--tool <name>` | The tool name (required) |
| `--amount <number>` | Amount to test against capped scopes |
| `--audience <audience>` | The grant token audience the relying party expects, passed to `enforce()` for this call. From version 0.4.0. |
| `--audience-check <on\|off>` | The client's grant token audience check: `on` (default) or `off`, which ignores `aud`. From version 0.4.0. |
| `--json` | Output machine-readable JSON |

***

## Exit Codes

| Code | Meaning |
| - | - |
| `0` | Tool call is allowed |
| `1` | Tool call is denied |
| `2` | Usage error (missing arguments, invalid token) |

***

## Related Commands

| Command | Description |
| - | - |
| [`grantex manifest list`](/cli/manifest) | Browse pre-built manifests (or load your own) |
| [`grantex manifest show <connector>`](/cli/manifest#grantex-manifest-show) | Inspect tools and permissions for a connector |
| [`grantex manifest validate`](/cli/manifest#grantex-manifest-validate) | Validate agent tools against a manifest |
| [`grantex verify`](/cli/verify) | Inspect a grant token's scopes, expiry, and delegation chain |

## Ownership

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.