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

> Usage and flags for oz0 agent new.

For: Operators and developers looking up a command.

Write \<name>.md in the current folder (or --dir): an agent in one file, its fields in the front matter and its instructions below, with apiVersion: oz0/v1, a description to fill in and the default model alias. It never writes a manifest, and never overwrites a file.

The file is a plugin of that one agent: `dev <name>.md` reloads it on every save on a dev server, `run <name>.md [INPUT]` runs it once on a dev server of its own, and `plugin install ./<name>.md` installs it in your cluster's tenant (on a terminal it shows what the agent needs, may do and reaches, and asks once, which also grants what it uses of other plugins), after which `run <name>` runs it.

The plugin's name and version come from the file: its name, and the digest of what was uploaded (or the tag or commit of a Git source).

--uses \<plugin> lists that plugin's functions by address, \<plugin>/\<tool>.\<function>, from the tenant's catalog when your CLI context's server answers: the Read ones on, the others written commented out with their type, to take the # out of the ones the agent needs. --tool \<address> lists exactly that function instead. Without a server it writes a commented example to fill in. Each function listed is granted at install, and the tenant's tool policy still decides each call.

## Usage

```bash
oz0 agent new <name> [flags]
```

## Flags

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

<tbody>
  <tr>
    <td>
      <code>
        --description
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        a line to fill in
      </code>
    </td>
    
    <td>
      what the agent does, in one line
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --dir
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        the current folder
      </code>
    </td>
    
    <td>
      the folder to write &lt;name>.md in
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --runtime
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the agent's runtime when it is not pydantic-ai: openai-agents, harness:&lt;name> or remote:&lt;name>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tenant
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        default
      </code>
    </td>
    
    <td>
      the tenant whose catalog --uses reads
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tool
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      one function the agent calls, by address, &lt;plugin>/&lt;tool>.&lt;function>; repeatable
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --uses
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      a plugin whose functions the agent calls, listed by address from the tenant's catalog; 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.