---
title: "oz0 secret set"
description: "Store a secret; the value comes from stdin, --from-env or --from-file, never from the command line."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/secret/set"
---
# oz0 secret set

> Store a secret; the value comes from stdin, --from-env or --from-file, never from the command line.

For: Operators and developers looking up a command.

Store a secret; the value comes from stdin, --from-env or --from-file, never from the command line.

The value goes to an edge first. When a provider record reads the secret (its key, or a SigV4 record's access key
ID or session token), the edge tests it with one call that spends nothing: the provider's list of models, or a token
request. A value the provider refuses is not stored. A secret no record reads calls no provider and is stored
untested.

--test also refuses a value no call could check, and waits out the edge's limit of 20 tests a minute;
--no-test --reason skips the edge and records why. The value it replaces is kept for 24 hours, so that "secret rollback" can bring it back, unless
--discard-previous (a key that leaked). --expires sets a date (2026-12-31) or a rotation period (90d) for reminders.

--host binds the value to the hosts it may be sent to (host, host:port or *.domain; repeat for more), sealed with it:
a plugin source's token (--auth-secret), a workspace export's push and pull request, a provider record's key or token
endpoint, and a webhook's signature (--signing) go only to these, whoever names the secret. A secret bound to no host is
sent nowhere, except that a built-in provider's key (ANTHROPIC_API_KEY, OPENAI_API_KEY and each preset's) also goes to
its own provider.

A set without --host keeps the binding the secret had; --unbind clears it. The binding changes only
with the value: set it again with the value to bind it elsewhere.

An incoming hook (a routine's or a flow's webhook, an event source) checks its requests only with a signing key bound
to the edge's own address its senders post to, with the port (--signing --host oz0-edge.acme.example:7443: the edge
API's advertised address, its --public-edge-url or a --san name), or with a secret a connection of its plugin saved.

--ref store:\<store>/\<path>[#\<field>] stores a reference to a secret store instead of a value: the edges that run the
store (oz0 secret stores) read the value there, and a new version in the store reaches the plugins that use it. A
reference goes only to the hosts its store lists on the edges.

## Usage

```bash
oz0 secret set <NAME> [flags]
```

## Flags

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

<tbody>
  <tr>
    <td>
      <code>
        --discard-previous
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      keep no previous value for a rollback (a key that leaked)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --expires
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      when the secret should be rotated: a date (2026-12-31) or a period (90d, 12w)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --from-env
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      read the value from this environment variable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --from-file
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      read the value from this file
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --host
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      a host the value may be sent to: host, host:port or *.domain (repeat for more); a plugin source's token, a workspace export's push, a provider's key or a webhook's signature goes only to these
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --no-test
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      store the value without testing it; needs --reason
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --reason
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      why the value is not tested (with --no-test), for the audit trail
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --ref
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      store a reference to a secret store instead of a value: store:&lt;store>/&lt;path>[#&lt;field>][@&lt;version>]
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --signing
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      a signing key: it signs webhook notifications to its --host, or checks the requests of a hook on the edge it names, and is never sent itself
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --test
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      refuse the value unless a provider's check took it (by default only a refusal stops it)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --unbind
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      bind the value to no host: no sink sends it anywhere
    </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>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      tenant
    </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.