---
title: "oz0 plugin import openapi"
description: "Usage and flags for oz0 plugin import openapi."
canonical_url: "https://docs.oz0.ai/reference/cli/oz0/plugin/import/openapi"
---
# oz0 plugin import openapi

> Usage and flags for oz0 plugin import openapi.

For: Operators and developers looking up a command.

Read an OpenAPI 3.0 or 3.1 document (YAML or JSON, a file or an https:// URL, which is fetched once, at most 16 MiB) and write an ordinary plugin into --out: an MCP server of fixed code from Orchestrator Zero's template and the document's operations as data (src/\<module>/operations.json).

Each operation becomes a function of the plugin's one tool, named after its operationId (or its method and path) in snake case; two operations that come to one name are refused, naming both. Its arguments are the path, query and header parameters and the request body as `body`, with $ref resolved (a recursive one cut where it comes back) and oneOf, allOf and formats kept; its output is the HTTP status and the JSON body, not checked against the document.

GET, HEAD and OPTIONS are marked read-only, DELETE destructive and the rest as writes, every one as reaching an outside API; every write (POST, PUT, PATCH, DELETE) asks a person by default through the plugin's suggested policy (policy:), decided by an operator who did not start the job, which the installer may switch with a reason (--writes-without-approval leaves them to the tenant's tool policy).

The server calls only the base URL's host (the document's first server, or --base-url), which is also the plugin's egress; it encodes every argument into its place and follows no redirect to another host. The credential (--auth, else the document's security scheme) is a tenant secret the node's egress proxy puts on the requests, so the plugin's process holds only a placeholder; --auth-secret gives the process the value instead, for nodes that cannot inject.

With --connection, an API on each tenant's own instance (a Jira, a GitLab) has no URL or secret fixed at import: each call gets its token and the instance's URL from that connection of the plugin, which the manifest declares with a step where an admin pastes both (replace it with the API's own sign-in where it has one), and the call goes to that instance only; --base-path sets the path under the instance's URL.

What could not be carried over is listed in the output and the plugin's README. Then: uv lock, plugin lint, plugin install.

## Usage

```bash
oz0 plugin import openapi <file | https-url> [flags]
```

## Flags

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

<tbody>
  <tr>
    <td>
      <code>
        --ai-label
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      where a function that writes what people read puts the tenant's AI label: &lt;function>=&lt;JSON pointer into its arguments>, such as add_comment=/body/body (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --allow-http
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      allow an http:// base URL, for a local test API without a credential
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --auth
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        the document's security scheme
      </code>
    </td>
    
    <td>
      how the API takes its credential: bearer, header:NAME, basic:USER, query:NAME or none
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --auth-secret
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      give the plugin's process the secret's value instead of binding it to the API's host for the node's egress proxy to inject
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --base-path
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        the document's first server's path; / for none
      </code>
    </td>
    
    <td>
      with --connection: the path under the instance's URL that the operations are under
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --base-url
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the API's base URL, instead of the document's first server (<code>
        https://
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --connection
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the plugin's connection that gives each call its token and the API's URL (an instance of the tenant's own), instead of a tenant secret and a URL fixed at import
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --force
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      rewrite a folder an earlier import wrote, keeping files it does not write (such as uv.lock)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --json
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      print what was written as JSON
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --name
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the plugin's name (lowercase letters, digits and dashes); its tool ID is the name with _ for -
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --operations
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      import only operations whose function name, operationId or "METHOD /path" matches this glob; * stops at /, so 'GET /invoices/*' matches GET /invoices/{id} but not GET /invoices (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --out
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      
    </td>
    
    <td>
      the folder to write the plugin into; it must be empty or not exist (see --force)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --quiet-budget
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      do not explain a result over the tool-size budget (the token count is still printed)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --rename
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      give a function a name of its own: &lt;operationId or "METHOD /path">=&lt;name>, such as search_1=search_issues (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --secret
      </code>
    </td>
    
    <td>
      string
    </td>
    
    <td>
      <code>
        &lt;NAME>_API_KEY
      </code>
    </td>
    
    <td>
      the tenant secret that holds the credential
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --tag
      </code>
    </td>
    
    <td>
      stringArray
    </td>
    
    <td>
      
    </td>
    
    <td>
      import only operations with this tag (repeatable)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        --writes-without-approval
      </code>
    </td>
    
    <td>
      bool
    </td>
    
    <td>
      
    </td>
    
    <td>
      leave the writes (POST, PUT, PATCH, DELETE) to the tenant's tool policy instead of having each ask a person by default
    </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.