plone-restapi-shell

A non-interactive, composable command-line shell over the core Plone REST API, built for automation agents.

Every invocation performs one logical operation and emits exactly one versioned JSON result envelope on stdout — on success and on failure alike — with a stable process-exit taxonomy that reports the failure class rather than an HTTP status.

$ plone-restapi --profile production content get --path /news
{"command":"content.get","meta":{…},"ok":true,"result":{…},"schema":"plone-restapi-shell/v1"}
$ echo $?
0

Installation

$ pipx install plone-restapi-shell

uv tool install plone-restapi-shell and plain pip install work as well. OS keyring support is the optional keyring extra. See docs/installation.md.

The shell also ships the agent skill for driving it, with a command reference rendered from its own command tree:

$ plone-restapi skill install          # into every known agent skills directory
$ plone-restapi skill update           # after upgrading the shell

Documentation

• Quick start — profile, credential, read, write, confirm, and the exit taxonomy.
• Agent idioms — the six obligations this shell puts on its caller, and the idiom for each.
• Command reference — every family and operation with its safety class.
• Releasing — version policy and the release gates.

plone-restapi <family> <operation> --help is the authoritative reference and needs no configuration, keyring, or network.

Verified against

Plone 6.2.0 with plone.restapi 10.0.2 is the maintained target and receives the full suite. Plone 6.1.5 and 6.0.15 are security-supported compatibility references verified by a smoke subset. CPython 3.10–3.14, on Linux, macOS, and Windows.

Development

$ make venv     # install the package and its tools
$ make check    # lint, types, and everything that needs no container
$ make gate     # the real-Plone suite with the 229/229 coverage gate

make help lists the rest. Implementation is tracked in issues/0023-implement-the-plone-restapi-shell-cli.md.

Licence

GPL-2.0-only. See LICENSE.