CLI reference

The plugin CLI lives under two command groups: tovio plugin (install, trust, inspect, validate, test, bind, run) and tovio policy hook (policy-integrated enforcing bindings).

All commands that produce machine-readable results support --json (REQ-PLUGIN-062).

Implemented

The tovio plugin command group, contracts, validation, and sandbox execution are shipped in the Team/Advanced CLI (REQ-PLUGIN-061), and so are Ed25519 publisher signatures, the local trust store, and bounded HTTPS installation. Execution needs a build with the sandbox compiled in — the default build has it; a --no-default-features build reports "built without plugin execution" rather than a false pass.

tovio plugin

tovio plugin install <source>

Install a plugin package into this repository's store (.tovio/plugins/<id>/), from either a local path or an HTTPS URL. Validates the manifest before anything is written, so a bad package stores nothing.

A local package is a directory holding manifest.toml plus at most one runtime artifact — or a bare manifest.toml on its own, which installs a manifest-only local-development package.

An HTTPS package URL must end in / or /manifest.toml and serve a sibling plugin.wasm. It must clear bounded retrieval (system-root TLS, connect/read time limits, response-size limits enforced while reading), the artifact SHA-256, the publisher signature, the trust store, and the revocation list before the local store changes (REQ-PLUGIN-089). URL credentials, fragments, queries, redirects, non-success responses, other schemes, and archive extraction are all refused, as are remote local_dev and hash-only packages.

$ tovio plugin install ./license-check          # a package directory
$ tovio plugin install https://plugins.example.com/license-check/1.2.0/

tovio plugin trust <add|revoke|list>

Manage the repository-local trust store of Ed25519 publisher identities (REQ-PLUGIN-087/088). Trust is granted per publisher, not per plugin, and revocation is enforced both at install and before every execution.

$ tovio plugin trust add did:key:<64 hex digits> --label "Example Corp"
$ tovio plugin trust revoke did:key:<64 hex digits> --reason "key compromise"
$ tovio plugin trust list --json

A revocation is permanent in this store and is never silently reversed — it may even be recorded before the trust it revokes.

tovio plugin uninstall <plugin-id>

Remove an installed plugin: its store directory goes, and any local binding that referenced it is dropped with it.

tovio plugin list

Show installed plugins — id, name, version, type, and declared events. --json yields the full inventory.

tovio plugin show <plugin-id>

Show one plugin's full validated manifest, its integrity status, and the local bindings that reference it, each with the capabilities that binding grants.

tovio plugin verify <plugin-id>

Re-verify an installed plugin's artifact hash, publisher signature, trust, and revocation state. Emits TVO-PLUGIN-003 on any failure, fail-closed. Local hash-only and explicit local_dev packages are reported as development-policy installs — never as publisher-verified.

tovio plugin validate <path>

Validate a manifest or package without installing it, and report the reason on failure. The CLI only reads the file; the check itself is the pure tovio-core PluginManifest::validate (REQ-PLUGIN-063). Writes nothing.

$ tovio plugin validate ./license-check          # a package directory
$ tovio plugin validate ./manifest.toml          # or the manifest alone

tovio plugin test <path> --event <event>

Run a plugin package over a sample event without installing it — the author's inner loop. It resolves the package the way install does (a directory with manifest.toml plus a runtime artifact), runs it in the sandbox under the manifest's own declared capabilities with no binding involved, and prints the result. A dev run never gates.

$ tovio plugin test ./license-check --event pre-land --json

Flags:

Flag	Meaning
--event <event>	Which lifecycle event to run for (required).
--json	Emit the full result envelope for programmatic use.

tovio plugin bind <plugin-id> --event <event> --mode advisory|enforcing

Create a local binding — not a repo/org/Forge policy gate (REQ-PLUGIN-025). It is refused if the plugin's manifest does not declare the event, or the event is unknown. The binding is written pinned to the exact version installed right now; the at_least version floor exists in the on-disk format but has no flag, so it is hand-authored. See Bindings for the precedence rules.

Flags:

Flag	Meaning
--event <event>	Which lifecycle event to bind (required).
--mode advisory\|enforcing	Binding mode (required).
--required	Add error/skipped/unsupported/unavailable to the blocking set. An enforcing binding already blocks on fail without this. An advisory binding marked required is recorded but never blocks.
--paths <globs>	Restrict by path (repeatable; empty ⇒ all).
--branches <globs>	Restrict by target lane/ref (repeatable; empty ⇒ all).
--grant <cap>	Grant one capability on this binding (repeatable). Deny-by-default, and the effective grant is always manifest ∩ binding, so this can never widen the manifest.
--grant-read-path <glob>	Grant one read_clear_paths glob (repeatable).

--grant takes any of read_protected_metadata, write_working_copy, write_plugin_cache, network_access, emit_audit, invoke_tovio_command, propose_resolution, propose_transform, block_operation. read_protected_plaintext is deliberately not flag-grantable: passing it is refused with TVO-PLUGIN-013 rather than silently dropped or silently honored.

tovio plugin unbind <plugin-id> --event <event>

Remove the local binding of that plugin to that event. --event is required; naming a pair with no existing binding is TVO-PLUGIN-004.

tovio plugin bindings

List every local binding, with plugin id, version requirement, mode, required, filters, and the granted capabilities. Supports --json.

tovio plugin run <plugin-id> --event <event> [--dry-run]

Run an installed, bound plugin over the current state in the capability-bounded sandbox. Its effective capabilities are the manifest ∩ binding intersection. An enforcing binding that reports fail makes the command exit non-zero, whether or not it is required.

$ tovio plugin run com.example.license-check \
    --event pre-land --dry-run --json

--dry-run reports the result and what would block without gating the operation.

tovio plugin doctor

Config-and-health sweep over the whole plugin store — no execution. Every manifest parses and validates, every artifact's integrity is checked, and every binding resolves to an installed plugin and a declared event. Reports healthy vs. broken and exits non-zero on any problem, so CI can gate on it.

tovio policy hook

The policy-integrated hook surface (REQ-PLUGIN-066..068): it attaches a plugin to a lifecycle event as an enforcing binding, whereas tovio plugin bind lets you choose the mode.

tovio policy hook add <event> <plugin-id> [--required] [--paths <globs>] [--branches <branches>]
                                          [--grant <cap>] [--grant-read-path <glob>]
tovio policy hook remove <event> <plugin-id>
tovio policy hook list

• tovio policy hook add creates or updates an enforcing binding (REQ-PLUGIN-067); the plugin must be installed and declare the event. Being enforcing, it already blocks on fail; --required adds error/skipped/unsupported/unavailable to that set.
• tovio policy hook list makes every hook, including its granted capabilities, inspectable by humans and agents (REQ-PLUGIN-068).
• The grant surface is the same deny-by-default one as plugin bind — including the refusal of read_protected_plaintext.

Hooks are local today

policy hook add writes into the same .tovio/plugins/bindings.toml store as plugin bind, with scope = "local". It is not yet a signed org-policy artifact, and a local result is not a Forge-side gate (REQ-PLUGIN-070). What the Forge enforces is an org allow/deny policy over plugin ids plus attested, revision-stamped plugin:<id> checks.

Related commands

• tovio explain plugin shows which plugins are bound to which events, advisory vs. enforcing, and their filters — without initializing or executing anything.
• tovio status surfaces blocking plugin state when relevant (REQ-PLUGIN-064).
• tovio land surfaces required plugin blockers (REQ-PLUGIN-065).
• tovio audit verify covers plugin audit fields as part of the signed audit body.
• tovio resolve --ai uses the plugin framework for configured resolver plugins (REQ-PLUGIN-078).

Global flags

Plugin commands honor the standard global flags — see Global flags. The ones that matter here:

• --json — machine-readable output on every command that produces a result (REQ-PLUGIN-062).
• -q / --quiet — suppress success and progress output; errors still print.

--justification is accepted here because it is a global flag, but no tovio plugin or tovio policy hook command writes an audit entry today, so it has no effect on this surface. What is audited is plugin execution: an enforcing run produces signed audit metadata (REQ-PLUGIN-058..060) that tovio audit verify covers.

Related

• CLI reference
• Errors

Last reviewed September 9, 2026

Suggest an improvement to this page  ·  Not for security reports — see disclosure