---
title: "oz0 approval allowlist"
description: "Usage and flags for oz0 approval allowlist."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/approval/allowlist"
---
# oz0 approval allowlist

> Usage and flags for oz0 approval allowlist.

For: Operators and developers looking up a command.

Approve a shell command the tenant's command rules asked a person about, and add a command rule that allows
such commands from now on; with --refuse, deny it and add a rule that refuses them. It is the approval card's
"Approve and always allow" and "Deny and always refuse".

The rule's pattern is suggested from the command's parse, never its text: the narrowest one, this command with
every argument pinned (the programs that feed it, such as a download piped into a shell, as earlier stages).

Without
--pattern the command prints the suggestion with the steps each token widens by, one at a time (a flag's value by its
last segment, module.test.vpc to module.test.*; a path to its class, [inside-workdir]; any other argument to *; then
** for the rest), and saves the narrowest. The program and its subcommand never widen.

What it will not save, each refused with its reason:

- an allow of a command the reader could not read: such a command always asks, so no allow can match it (--refuse
writes a refuse over the floor, cmd.unreadable, for the agent instead);
- an allow that names only a program a default asked about (rm **, terraform **), or leaves a subcommand open;
- an allow of running what a command downloads, unless every URL is written out in full over https and its host is
on the tenant's egress list: what a URL serves can change after it was approved, so download it, check its hash,
then run it;
- a pattern that would not decide this very command as asked (one broader than the default that asked, which then
still asks first), or a token that looks like a credential.

The rule applies to the agent that asked (--scope agent, the default), the agents of one plugin (--scope plugin
--plugin NAME) or every agent (--scope tenant); it lasts 30 days unless --for says 7d or none, may start in shadow
mode (--shadow), and records the approval and job it came from, who proposed it and why (--reason, required).

A refuse
acts at once; an allow acts at once unless the tenant has four eyes on, when it waits as a change request for another
admin (oz0 change list). Someone who decides approvals but may not change the tool policy files either for a tenant
admin. The approval is decided as well: approved for an allow, denied for a refuse, with the reason as its comment.

The impact line counts what the rule would have allowed (or refused) among the last 30 days' command decisions in the
audit trail. Those entries keep the program and what the defaults found, never the command, so it is at most that
many; it is one line, not a full preview of the change. --preview prints the suggestion and the checks and saves
nothing. The command is the job's content: reading it takes the content permission.

The edge signs a receipt for the
card, for you, which management checks before it takes the rule: this needs the job's node up.

## Usage

```bash
oz0 approval allowlist JOB APPROVAL [flags]
```

## Flags

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --decision-ref
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the decision or case the change follows, such as a case number (at most 200 characters)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --for
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        30d
      </code>
    </td>
    
    <td>
      how long the rule lasts: 7d, 30d or none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      print JSON instead of a table
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --pattern
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        the suggested narrowest one, this command pinned
      </code>
    </td>
    
    <td>
      the rule's pattern
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --plugin
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the plugin whose agents a --scope plugin rule applies to
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --preview
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      print the suggestion, the checks and the impact line, and save nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --reason
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      why, required for every governance change (at most 500 characters; default $OZ0_REASON); the audit log keeps it
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --refuse
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      deny the command and refuse such commands always, instead of approving and allowing them
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --scope
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        agent
      </code>
    </td>
    
    <td>
      whose jobs the rule applies to: agent (the agent that asked), plugin (with --plugin) or tenant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --shadow
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      start the rule in shadow mode: it decides nothing and records what it would have decided
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      tenant
    </td>
  </tr>
</tbody>
</table>

## Inherited flags

<table>
<thead>
  <tr>
    <th>
      Flag
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        --context
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        $OZ0_CONTEXT or &lt;config dir>/orchestrator-zero/context.json
      </code>
    </td>
    
    <td>
      CLI context file written by server init
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --log-level
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        info
      </code>
    </td>
    
    <td>
      log level: debug, info, warn or error
    </td>
  </tr>
</tbody>
</table>

See [all `oz0` commands](https://docs.oz0.ai/reference/cli/oz0) and the [global flags](https://docs.oz0.ai/reference/cli/oz0#global-flags).


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.