---
title: "overlane guard rules test"
description: "Test a rule file against an action, locally, before it is merged"
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# overlane guard rules test

{/* Generated by apps/docs/scripts/generate.mjs (CLI pages from the command registry in packages/cli). Do not edit; run `pnpm --filter @overlane/docs gen`. */}

Loads a rule file (JSON, version 1) and evaluates one action against it as the team layer, with no network. The server also applies the platform rules, which a team file cannot weaken; use `overlane guard dry-run` to see the combined decision. Exits 6 when the file would refuse the action.

## Usage

```sh
overlane guard rules test --file PATH --tool TOOL [--path PATH...] [--branch BRANCH] [--repo OWNER/NAME] [--environment NAME] [--host HOST] [--role owner|admin|member|viewer|agent] [--usage METRIC=N...]
```

## Flags

| Flag | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `--file` | string | yes |  | The rule file to test |
| `--tool` | string | yes |  | The action, for example git.push, deploy.run, egress.fetch or api.write |
| `--path` | string (repeatable) | no |  | A path the action touches; repeat for more |
| `--branch` | string | no |  | The branch the action targets |
| `--repo` | string | no |  | The repository the action targets |
| `--environment` | string | no |  | The environment, for example production |
| `--host` | string | no |  | The host, for an egress action |
| `--role` | one of `owner`, `admin`, `member`, `viewer`, `agent` | no | `agent` | The role of the principal |
| `--usage` | string (repeatable) | no |  | Measured usage, for example usd=12.5 or reviews=50 |

## Examples

```sh
overlane guard rules test --file rules.json --tool git.push --branch main --role agent
overlane guard rules test --file rules.json --tool review.run --usage reviews=50
```

## Behavior

- Effect: `read` (changes nothing).
- Needs credentials: no. Uses the network: no.
- Supports `--dry-run`: no. Accepts `--force`: no.
- Machine-readable description: `overlane schema guard rules test`.

## Result

With `--json` (the default when stdout is not a terminal) the command prints this JSON Schema's shape on stdout.

```json
{
  "type": "object",
  "properties": {
    "decision": {
      "type": "object",
      "properties": {
        "tenantId": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$",
          "description": "tenant identifier"
        },
        "effect": {
          "type": "string",
          "enum": [
            "allow",
            "deny",
            "require_approval"
          ]
        },
        "allowed": {
          "type": "boolean"
        },
        "code": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "policy_denied",
                "approval_required",
                "protected_branch",
                "path_protected",
                "spend_cap_reached",
                "plan_limit_reached",
                "egress_blocked",
                "deploy_blocked",
                "secret_detected",
                "task_required"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "ruleId": {
          "type": [
            "string",
            "null"
          ]
        },
        "layer": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "platform",
                "team",
                "project"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "message": {
          "type": "string",
          "minLength": 1
        },
        "nextCommand": {
          "type": [
            "string",
            "null"
          ]
        },
        "exitCode": {
          "anyOf": [
            {
              "type": "number",
              "const": 0
            },
            {
              "type": "number",
              "const": 6
            }
          ]
        },
        "dryRun": {
          "type": "boolean"
        },
        "wouldBlock": {
          "type": "boolean"
        },
        "approvalId": {
          "type": "string"
        },
        "matched": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "ruleId": {
                "type": "string",
                "minLength": 1
              },
              "layer": {
                "type": "string",
                "enum": [
                  "platform",
                  "team",
                  "project"
                ]
              },
              "effect": {
                "type": "string",
                "enum": [
                  "allow",
                  "deny",
                  "require_approval"
                ]
              },
              "dryRun": {
                "type": "boolean"
              }
            },
            "required": [
              "ruleId",
              "layer",
              "effect",
              "dryRun"
            ],
            "additionalProperties": false
          }
        }
      },
      "required": [
        "tenantId",
        "effect",
        "allowed",
        "code",
        "ruleId",
        "layer",
        "message",
        "nextCommand",
        "exitCode",
        "dryRun",
        "wouldBlock",
        "matched"
      ],
      "additionalProperties": false
    },
    "rules": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "note": {
      "type": "string"
    }
  },
  "required": [
    "decision",
    "rules",
    "note"
  ],
  "additionalProperties": false
}
```

See [exit codes](/cli/#exit-codes) for the status the process returns.

Source: https://docs.overlane.app/cli/guard-rules-test/index.mdx