Plugin CLI reference

The ados plugin subcommand tree is the operator and developer interface to the agent’s plugin host: install, enable, inspect, sign, and lint plugins. This page documents all 15 subcommands, their flags, and the exit codes every command shares. The plugin group is not listed in ados help, but it is always available. Run ados plugin --help on the agent for the command list, or ados plugin <command> --help for a single command. The lifecycle commands talk to the local agent’s /api/plugins routes, so run them on the node.

The `--json` flag

Every subcommand accepts --json. With it, the command prints a single machine envelope to stdout instead of human-readable text:

{ "ok": true, "code": 0, "kind": "ok", "data": ... }

On failure the envelope carries the error:

{ "ok": false, "code": 3, "kind": "signature_invalid", "detail": "...", "hint": "..." }

code is the process exit code (see Exit codes), kind is the stable string form of that code, data is the per-command payload, and hint (when present) is a suggested next step. Use the JSON form in scripts and CI; parse .ok and .code rather than the human text, which is not stable.

Exit codes

Every ados plugin subcommand returns one of these codes. The JSON envelope’s kind field carries the same meaning as a string.

Code	Kind	Meaning
0	`ok`	Success
1	`generic_failure`	Unclassified failure
2	`manifest_invalid`	The `manifest.yaml` is missing or fails validation
3	`signature_invalid`	The archive signature did not verify against an enrolled key, or the archive is unsigned. The hint names `ADOS_PLUGIN_REQUIRE_SIGNED`; see Bench install and signing
4	`permission_denied`	A capability change was refused: `--yes` on a high-risk plugin, or a first-party-only gate (`refused: ..._first_party_only`) such as `gcs.isolation: inline` or `resources.class: heavy` from another signer
5	`plugin_not_found`	No plugin with that id is installed, or a file the command needs is missing
6	`wrong_state`	The plugin is in a state the command cannot act on
7	`resource_limit`	A declared resource budget was exceeded
8	`compatibility_failed`	The plugin does not fit this agent: its `ados_version`, board, tier, target profile or architecture, or `isolation: inprocess`, which is refused for every plugin

Lifecycle commands

`list`

List installed plugins.

ados plugin list
ados plugin list --all
ados plugin list --json

Flag	Meaning
`--all`	Also list the built-in plugins that ship with the agent but are not installed
`--json`	Machine-readable output

The human table prints ID, VERSION, STATUS, and SIGNER. With --all, a built-in that is not installed shows status available and signer -; install one with ados plugin install <id>. Installed built-ins show their real status.

`install`

Install a plugin from a local archive, an archive URL, a built-in plugin id, or a first-party catalog id. The command drives the agent’s native /api/plugins routes: it previews first, asks for approval, then installs and grants the permissions you approved.

ados plugin install dist/com.example.thermal-1.0.0.adosplug
ados plugin install https://github.com/example/thermal/releases/download/v1.0.0/com.example.thermal-1.0.0.adosplug
ados plugin install com.altnautica.world-engine

Argument / flag	Meaning
`SOURCE`	A `.adosplug` path that exists, an `https://` URL on the agent’s download allowlist, a built-in plugin id, or a catalog plugin id
`--yes`	Skip the interactive permission-approval prompt. Refuses high-risk and critical-risk plugins
`--json`	Machine-readable output

The preview verifies the signature and validates the manifest, then prints the plugin id, its risk level, and the permissions requested, and prompts for approval. If you decline, nothing is installed and the command exits 0. The install itself checks compatibility, including the node profile and the host architecture, before anything is unpacked. A URL install is pinned to the sha256 of the archive you reviewed; a catalog install is pinned to the catalog’s sha256. --yes approves the listed permissions without a prompt, but it refuses any plugin whose risk is high or critical (exit 4); re-run those interactively. A signature failure exits 3, a bad manifest exits 2, a compatibility mismatch exits 8. With --json and no --yes, the plugin installs with no permissions granted; grant them with ados plugin perms <id> --grant <cap>, or add --yes. After a successful install the plugin is installed but stopped. Enable it next:

ados plugin enable com.example.thermal

`enable`

Enable an installed plugin so the host starts it.

ados plugin enable com.example.thermal

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--json`	Machine-readable output

Exits 5 if no plugin with that id is installed.

`disable`

Disable a plugin. It stays installed, with its grants intact, but the host stops running it.

ados plugin disable com.example.thermal

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--json`	Machine-readable output

`remove`

Stop, uninstall, and forget a plugin.

ados plugin remove com.example.thermal
ados plugin remove com.example.thermal --keep-data

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--keep-data`	Keep the plugin’s log, data directory and system user. Without it, remove deletes all three
`--json`	Machine-readable output

Inspection commands

`info`

Print a manifest summary and runtime state for one plugin.

ados plugin info com.example.thermal
ados plugin info com.example.thermal --json

Argument / flag	Meaning
`PLUGIN_ID`	An installed or built-in plugin id
`--json`	Machine-readable output

The human output lists the version, status, signer, install source, and each permission with its grant state. Exits 5 if the id is neither installed nor a built-in.

`perms`

Show, grant, or revoke permissions on an installed plugin.

# show
ados plugin perms com.example.thermal

# grant a permission the plugin declares
ados plugin perms com.example.thermal --grant mavlink.read

# revoke one capability
ados plugin perms com.example.thermal --revoke mavlink.write
ados plugin perms com.example.thermal --revoke mavlink.write --yes

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--grant ID`	Grant a permission the plugin declares
`--revoke ID`	Revoke a specific capability id
`--yes`, `-y`	Skip the revoke confirmation prompt
`--json`	Machine-readable output

With neither flag, the command lists each recorded permission as GRANTED or DENIED. Pass --grant or --revoke, not both. A revoke confirms intent (unless -y or --json), then takes effect at once: the host re-mints the plugin’s token without the capability, which can interrupt a running workload. Exits 5 if the plugin is not installed.

`logs`

Print or follow a plugin’s stdout and stderr log.

ados plugin logs com.example.thermal
ados plugin logs com.example.thermal --lines 500
ados plugin logs com.example.thermal --follow
ados plugin logs com.example.thermal --service worker

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--lines N`	Number of trailing lines to print (default 100)
`--follow`	Follow the log like `tail -f`. Ctrl-C to stop
`--service NAME`	Read a declared service’s log instead of the main process’s
`--json`	Machine-readable output (non-follow only)

The command asks the agent for the log path (GET /api/plugins/<id>), so it always reads the file the host writes: /var/log/ados/plugins/<id with dots as hyphens>-<hash8>.log, or ...-<hash8>-<service>.log for a declared service. An unknown --service exits 2 and lists the declared services. Exits 5 if the log file does not exist yet (the plugin may never have started, or its log was rotated out).

Update commands

`pin`

Pin a plugin to a version so auto-update skips it.

ados plugin pin com.example.thermal 1.2.0

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`VERSION`	The version to pin to
`--json`	Machine-readable output

`unpin`

Clear the pinned version so auto-update can run again.

ados plugin unpin com.example.thermal

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`--json`	Machine-readable output

`auto-update`

Toggle auto-update on or off for one plugin.

ados plugin auto-update com.example.thermal on
ados plugin auto-update com.example.thermal off

Argument / flag	Meaning
`PLUGIN_ID`	The installed plugin id
`STATE`	`on` or `off`
`--json`	Machine-readable output

Developer commands

These commands run on a developer workstation against a plugin directory or a packed archive, not against installed plugins.

`lint`

Run static analysis on a packed .adosplug archive before submission.

ados plugin lint dist/com.example.thermal-1.0.0.signed.adosplug
ados plugin lint --json dist/com.example.thermal-1.0.0.signed.adosplug

Argument / flag	Meaning
`ARCHIVE_PATH`	Path to the packed `.adosplug` archive (must exist)
`--json`	Machine-readable output

Exits 0 when the report passes, 1 when it carries a finding at severity error or critical, 2 when the manifest is invalid. The full rule set is documented under Linting.

`test`

Run a plugin’s pytest suite under the SDK test harness.

ados plugin test ./my-extension
ados plugin test ./my-extension --tests-dir tests -k follow

Argument / flag	Meaning
`PLUGIN_DIR`	The plugin directory (must contain a `manifest.yaml`)
`--tests-dir DIR`	Subdirectory holding the pytest tests (default `tests`)
`-k EXPRESSION`	A pytest `-k` expression passed through to the runner
`--json`	Machine-readable output

The command validates the manifest, sets ADOS_PLUGIN_ID, ADOS_PLUGIN_VERSION, ADOS_PLUGIN_ROOT, and (when declared) ADOS_PLUGIN_TEST_FIXTURES in the environment, then shells out to pytest so your tests run against the canonical runner. Exits 0 when pytest passes, 1 when it fails, 2 on a bad manifest, 5 when the tests directory is missing.

`sign`

Pack a plugin directory into a signed .adosplug archive.

ados plugin sign ./my-extension \
  --key keys/acme-2026-A.priv.pem \
  --signer-id acme-2026-A \
  --output dist/com.example.foo-1.0.0.adosplug

Argument / flag	Meaning
`PLUGIN_DIR`	The plugin directory (must contain a `manifest.yaml`)
`--key PATH`	The Ed25519 private key in PEM format (required)
`--signer-id ID`	The signer id written to the `SIGNATURE` file. Must match the public-key filename on the agent (required)
`--output PATH`	Output path for the signed archive (required)
`--json`	Machine-readable output

The command packs the directory, computes the canonical payload hash (SHA-256 over the sorted entry hashes), signs that digest with the Ed25519 key, and writes a SIGNATURE entry into the archive plus a .sha256 checksum file next to it. The signing details and the monorepo-CI alternative (pack.sh and sign.sh) are covered under Signing keys.

`keygen`

Generate a fresh Ed25519 keypair for plugin signing.

ados plugin keygen acme-2026-A --output-dir keys
ados plugin keygen acme-2026-A --output-dir keys --force

Argument / flag	Meaning
`SIGNER_ID`	The signer id; becomes the key filenames
`--output-dir DIR`	Directory to write the keypair into (required)
`--force`	Overwrite existing key files at the target paths
`--json`	Machine-readable output

Writes <signer-id>.pem (the public key, mode 0644) and <signer-id>.priv.pem (the private key, mode 0600) under the output directory, and prints a SHA-256 fingerprint of the public key for cross-checking. Install the public PEM on each agent at /etc/ados/plugin-keys/<signer-id>.pem and keep the private half offline.

keygen is a developer aid. Production publisher keys deserve a hardware-token or air-gapped workflow, not a one-liner. Never commit a .priv.pem file.

Next steps

Lifecycle

The states these commands move a plugin through.

Signing keys

Keys for sign and keygen, and how a node trusts them.

Linting

The rules ados plugin lint applies.

Troubleshooting

What to do when a command exits non-zero.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

The `--json` flag

Exit codes

Lifecycle commands

`list`

`install`

`enable`

`disable`

`remove`

Inspection commands

`info`

`perms`

`logs`

Update commands

`pin`

`unpin`

`auto-update`

Developer commands

`lint`

`test`

`sign`

`keygen`

Next steps

Lifecycle

Signing keys

Linting

Troubleshooting

​The --json flag

​Exit codes

​Lifecycle commands

​list

​install

​enable

​disable

​remove

​Inspection commands

​info

​perms

​logs

​Update commands

​pin

​unpin

​auto-update

​Developer commands

​lint

​test

​sign

​keygen

​Next steps

Lifecycle

Signing keys

Linting

Troubleshooting

The `--json` flag

Exit codes

Lifecycle commands

`list`

`install`

`enable`

`disable`

`remove`

Inspection commands

`info`

`perms`

`logs`

Update commands

`pin`

`unpin`

`auto-update`

Developer commands

`lint`

`test`

`sign`

`keygen`

Next steps