---
title: "oz0 notify rule put"
description: "Add a notification rule, or replace one with --id."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/notify/rule/put"
---
# oz0 notify rule put

> Add a notification rule, or replace one with --id.

For: Operators and developers looking up a command.

Add a notification rule, or replace one with --id.

A rule names events (--event, repeatable): approval.waiting, approval.escalated, approval.expired, question.waiting,
budget_request.waiting, job.failed, budget.share, eval.regression, model.changed, tool_rule.expiring,
secret.expiring, quality.drift and model.retiring. It may narrow them to agents, tools (\<tool> or
\<tool>.\<function>, * for anything) and risk classes (read_only, destructive, open_world, undeclared), and it sends
them to targets:

--email-role admin       email to the tenant's members of a role (and the roles above it)
--email-team payments    email to a team's members
--email-person ana       email to an account, by name (never by address)
--webhook URL --secret S a signed POST to URL; S is the tenant secret its HMAC key is in
--channel CHANNEL:ROOM   a chat channel's room, such as teams:19:abc@thread.tacv2 (a room a verified message came
from, for Teams); its readers get the facts only, and an approval's buttons
--channel-person teams:ana  an account's private chat with the bot, through their linked chat identity; also
--channel-team and --channel-role. The call's details only for people who may read them

People get mail at the address their identity provider gives, or the one they set with oz0 notify address; email
needs the SMTP relay the operator configures (orchestrator-zero server --smtp-addr).

A notification carries the
event's facts (tenant, agent, tool, the job's link, the deadline and the step), never the call's arguments unless the
tenant's admins set notify-content to arguments, and never a link or code that decides: people decide in OZ, and a
webhook's receiver decides through the runtime API with an API key, then polls ListApprovals for the outcome.

That
key decides only the approvals its webhook was sent (or whose deciders name it): name it with --decide-key, the
key's ID as oz0 apikey list shows it. Any other key is refused. A put that names a key, sends a named key other
approvals or moves its webhook is a governance change: it takes --reason (default $OZ0_REASON), and where the tenant
has four eyes on it waits for another admin; taking a key out applies at once.

## Usage

```bash
oz0 notify rule put NAME [flags]
```

## Flags

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

<tbody>
  <tr>
    <td>
      <code>
        --agent
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      only this agent's events; repeatable, * matches anything
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --channel
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      post to a chat channel's room, CHANNEL:ROOM; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --channel-person
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      post to an account's private chat with a channel's bot, CHANNEL:ACCOUNT; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --channel-role
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      post to the private chats of a role's members with a channel's bot, CHANNEL:ROLE; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --channel-team
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      post to a team's members' private chats with a channel's bot, CHANNEL:TEAM; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --decide-key
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the ID of the API key the webhooks' receiver decides the approvals it is sent with
    </td>
  </tr>
  
  <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>
        --disabled
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      keep the rule but send nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --email-person
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      email this account, by name; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --email-role
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      email the tenant's members of this role: reader, operator, admin or owner; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --email-team
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      email this team's members; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --event
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      an event the rule sends; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --id
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      replace this rule
    </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>
        --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>
        --risk
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      only calls of this risk class: read_only, destructive, open_world, undeclared; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --secret
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the tenant secret webhooks are signed with (HMAC-SHA256): a signing key bound to the webhook's host (oz0 secret set NAME --host HOST --signing)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      tenant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tool
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      only this tool's or function's events; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --webhook
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      post signed JSON to this https URL; repeatable
    </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.