---
title: "oz0 plugin update"
description: "Resolve an installed plugin's ref again."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/plugin/update"
---
# oz0 plugin update

> Resolve an installed plugin's ref again.

For: Operators and developers looking up a command.

Resolve an installed plugin's ref again. A plugin installed from a hub listing (hub:\<name>) resolves its listing again, in the index it came from, and moves to the newest active version listed there when that is newer than the installed one, with the same checks as an install. A new commit runs its evals on a test node first, when it has any, and rolls out to canaries first when the plugin runs on two or more nodes.

A new commit that breaks the agents' contracts needs a new major version or --allow-breaking. An update that would take the plugin from new hands (a listing whose custody changed: another publisher, repository owner or custody epoch; or a Git repository transferred to another owner) changes nothing yet: it files a change request that a tenant admin approves after reading who the plugin came from and who it would come from (oz0 change show), and the approval runs the update.

A Git repository deleted and created again under the same URL is refused. A listing that moved to another name is not followed by a plain update, which says where it went; --follow-move follows it, when both listings state the move, as a change of hands to approve, and the plugin keeps its grants, settings, secrets, tool policy and history.

An install or update is checked against every installed plugin whose uses: names the plugin: the new version must be in the range each declares, and still have every function, agent and skill each one is granted. Otherwise it is refused with the list (oz0 plugin dependents \<name> shows all of them); --force --reason \<why> installs it anyway, and the audit log keeps the reason with the list (plugin.update.forced).

The version's gate and rollout check again, and stop for a plugin installed in the meantime that the force did not name.

Before it installs, when its input, output and errors are all a terminal and without --json, it shows what the plugin needs (secrets, settings, connections, model aliases and grants), what it may do (every function grouped by type, Read, Write, Sends out, Destructive or Unknown, with its default, Allow, Ask or Refuse, and why) and what it reaches (hosts, events that start jobs, secrets by name), and asks once; yes there grants what the plugin asks of other plugins too.

Anywhere else it behaves as --yes: it takes the defaults, grants only what --accept-uses, --accept-provides, --accept-reads and --accept-model say, and prints the same three blocks after the install. $OZ0_YES=1 does the same as --yes, for scripts run by hand from a terminal.

--policy \<function>=\<allow|ask|refuse> changes one function's default (repeatable; a group such as write or sends-out works too), and --config \<file> takes an oz0.plugin-config/v1 file (oz0 plugin config export writes one): its settings and tools are set after the install, the rest is filed as the plugin's configuration change. A switch changes the tool policy, so it takes --reason (or $OZ0_REASON); a loosening waits for another admin where four eyes are on.

A set (a plugin of kind set) installs its members, each pinned to an exact version and source, with what they use of other plugins, as one decision: the SET block lists each member and what the install does with it (install, update to the pin, keep at the pin, or keep a newer version or one from another source, which differs from what the set's evals ran on), and each member's own needs, may do and reaches follow.

On a terminal, yes also takes the settings and model mappings the set suggests; --suggested takes them anywhere else. The set's digest is one --accept-uses.

## Usage

```bash
oz0 plugin update <name> [flags]
```

## Flags

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

<tbody>
  <tr>
    <td>
      <code>
        --accept-inventory
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      for a Claude Code plugin, an Agent Plugin or an MCP Registry entry whose hooks or MCP commands changed: the digest of the new inventory you accept
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --accept-model
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      grant a plugin whose tools declare uses_model to call a model through the gateway in its calls, metered and budgeted to the calling job and under the tenant's data rules (the same as --accept-reads model)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --accept-provides
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      grant what the plugin's manifest says it provides beyond its own calls, such as outside-spend (spend that belongs to no job); comma-separated or repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --accept-reads
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      grant what the plugin's manifest says its functions read beyond their own calls, such as inventory (the tenant's agents as the inventory records them); comma-separated or repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --accept-uses
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      grant the plugin's uses of other plugins, and install the plugins it uses that the tenant lacks, by the digest a refused install printed
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --all-at-once
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      give a new version to every node at once, instead of rolling it out to canaries first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --allow-breaking
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      install a version whose agents' contracts break the installed version's, without a new major version
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --approve-egress
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      when the plugin's egress widens what the tenant permits, approve the change request it makes at once, after printing its delta (you must be allowed to approve it yourself)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --batch
      </code>
    </td>
    
    <td>
      int32
    </td>
    
    <td>
      <code>
        half of the rest
      </code>
    </td>
    
    <td>
      nodes in each later step of a rollout
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --canary
      </code>
    </td>
    
    <td>
      int32
    </td>
    
    <td>
      <code>
        1
      </code>
    </td>
    
    <td>
      nodes in a rollout's first step
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --config
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      an oz0.plugin-config/v1 file to apply after the install: its settings and tools at once, the rest as the plugin's configuration change
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dependency
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      &lt;plugin>=&lt;source>: where to install a plugin it uses that the tenant lacks (a Git URL, hub:&lt;name>, oci://..., mcp:&lt;name>); repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --follow-move
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      follow the plugin's listing to the listing it moved to, when both state the move; a tenant admin approves it as a change of hands
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --force
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      install or update it although it breaks installed plugins that use it (takes --reason)
    </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>
        --no-gate
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      roll out a version with evals at once, without running them on a test node first
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --policy
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      &lt;function or group>=&lt;allow|ask|refuse>: change one function's default, or a group's (read, write, sends-out, destructive, unknown); repeatable; takes --reason
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-cascade
      </code>
    </td>
    
    <td>
      points
    </td>
    
    <td>
      
    </td>
    
    <td>
      how many points more of the candidate's jobs may go to a later model of their cascade before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-denials
      </code>
    </td>
    
    <td>
      points
    </td>
    
    <td>
      
    </td>
    
    <td>
      how many points more of the candidate's approvals people may deny before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-min-jobs
      </code>
    </td>
    
    <td>
      int32
    </td>
    
    <td>
      <code>
        the plugin's configuration, else 10; only lower
      </code>
    </td>
    
    <td>
      the fewest jobs each version needs in a quality signal for it to count, 1 to 1000
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-outcome
      </code>
    </td>
    
    <td>
      points
    </td>
    
    <td>
      
    </td>
    
    <td>
      how many points more of the candidate's jobs than the installed version's may fail their outcome check's first round before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-reported
      </code>
    </td>
    
    <td>
      points
    </td>
    
    <td>
      
    </td>
    
    <td>
      how many points more of the candidate's reported results may be failures before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quality-sampled
      </code>
    </td>
    
    <td>
      points
    </td>
    
    <td>
      
    </td>
    
    <td>
      how many points more of the candidate's sampled jobs a sampled judge may fail before the step fails and the candidate rolls back (0 to 1, 0.1 is 10 points, or off; default the plugin's configuration, else 0.1; only stricter)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --reads-target
      </code>
    </td>
    
    <td>
      strings
    </td>
    
    <td>
      
    </td>
    
    <td>
      with --accept-reads results: a plugin whose results (findings, eval cases, refused approvals, errors, cost, scorecards) the plugin's agents may read, answered with your permissions at every read; comma-separated or repeatable; none, and it reads nothing
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --reason
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      why a forced install or update goes past the plugins that use it (at most 500 characters; default $OZ0_REASON)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --shadow-runs
      </code>
    </td>
    
    <td>
      int32
    </td>
    
    <td>
      <code>
        5
      </code>
    </td>
    
    <td>
      recent real inputs the quality gate replays on the new version, side effects stubbed, when too few real jobs end there; 0 for none, at most 20
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --soak
      </code>
    </td>
    
    <td>
      duration
    </td>
    
    <td>
      <code>
        1m
      </code>
    </td>
    
    <td>
      how long each step of a rollout is watched before its gates
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --start-timeout
      </code>
    </td>
    
    <td>
      duration
    </td>
    
    <td>
      <code>
        5m
      </code>
    </td>
    
    <td>
      how long a step's nodes may take to run the new version
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --suggested
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      for a set: take the settings and model mappings it suggests for its members without being asked
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      tenant
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --yes
      </code>
      
       (<code>
        -y
      </code>
      
      )
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      take the defaults without asking (what happens anywhere but on a terminal; $OZ0_YES=1 does the same)
    </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.