oz0 plugin inspect
For: Operators and developers looking up a command.
Describe a plugin as a plugin index lists it: its contents (agents, flows, tools, hooks, skills, harnesses), contracts, requirements, the permissions its code and manifest give it (shell and write tools, network and egress, secrets, hooks), its evals, licence and digests. Everything comes from the code, never from what its authors say about it, and the output is sorted, so the same commit gives the same bytes.
From a Git URL it resolves --ref to a commit, packs it as the edge does, and with --json prints the listing's source too, pinned to the commit, the SHA-256 of the packed content and the forge's repository ID (asked from GitHub, GitLab or Gitea; --forge none skips it). From a bundle file, as plugin pack builds it, the source pins the bundle's SHA-256 at --url, where it will be published.
From an oci:// reference with a digest it pulls the artifact (anonymously) and the source pins that digest. A local folder is packed as it is, with no source.
Inspect runs no plugin code: a tool's functions are listed only from the bundle's measured listing (tools.listing.json, which plugin test and plugin pack --list-tools write), with an estimate of what each definition costs per model request and each agent's capability card (its contracts, its tools' read, write and destructive counts, approvals and delegations); other tools are not listed, and every server counts as unchecked.
With --docs-dir it also writes the files the listing's docs name (the README, the images it shows from the package, every licence file and the graph of the plugin's parts) into that folder, each named by the 64 hex of its SHA-256, as an index's site serves them; a file already there with the same bytes is left as it is.
Usage
oz0 plugin inspect <git-url | dir | bundle.tar.gz | oci://registry/repository@sha256:digest> [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--allow-local | bool | let a remote source reach every address, this machine's included, and plain http:// and file://, for a repository or registry you serve yourself; without it a remote source reaches public addresses over https:// only, and the networks --allow-net lists | |
--allow-net | strings | a private network, such as 10.20.0.0/16, a remote source may reach over https://; this machine's own addresses (inside a listed network too), its link and metadata services need --allow-local; repeatable | |
--docs-dir | string | also write the README, its images, the licence files and the graph into this folder (created if missing), each named by its SHA-256, for an index's site to serve | |
--files | string | also write the inspected files into this folder, which must be empty or not exist, for scanners to read | |
--forge | string | from the host | the forge that hosts the repository: github, gitlab, gitea or none |
--json | bool | print the listing as JSON (schemas/plugin-index/v1/listing.schema.json) | |
--path | string | the plugin's folder in the repository | |
--ref | string | branch, tag or full commit SHA (default: the latest release tag, else the default branch); the listing pins the commit | |
--repository-id | string | the forge's ID of the repository, instead of asking the forge | |
--test-report | string | a report of plugin test --report of exactly these files, to carry in the listing (the version is validated when its evals passed) | |
--token-env | string | the name of an environment variable holding a token for a private Git source: sent to its host only, for the fetch and the repository ID | |
--url | string | for a bundle file: the https:// URL it will be published at, for the listing's source |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--context | string | $OZ0_CONTEXT or <config dir>/orchestrator-zero/context.json | CLI context file written by server init |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0 commands and the global flags.