overlane guard rules test

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

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

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.

{
  "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 for the status the process returns.