Metadata-Version: 2.5
Name: plone-restapi-shell
Version: 0.2.0
Summary: A non-interactive, composable command-line shell over the core Plone REST API.
Project-URL: Homepage, https://github.com/MrTango/plone-restapi-shell
Project-URL: Source, https://github.com/MrTango/plone-restapi-shell
Project-URL: Issues, https://github.com/MrTango/plone-restapi-shell/issues
Author-email: Maik Derstappen <md@derico.de>
License-Expression: GPL-2.0-only
License-File: LICENSE
Keywords: agent,automation,cli,plone,restapi
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: 6.2
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: click>=8.1
Requires-Dist: httpx>=0.27
Requires-Dist: platformdirs>=4.2
Requires-Dist: tomli>=2.0; python_version < '3.11'
Provides-Extra: keyring
Requires-Dist: keyring>=25.0; extra == 'keyring'
Description-Content-Type: text/markdown

# 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.

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

## Installation

```console
$ 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](docs/installation.md).

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

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

## Documentation

- [Quick start](docs/quickstart.md) — profile, credential, read, write,
  confirm, and the exit taxonomy.
- [Agent idioms](docs/agent-idioms.md) — the six obligations this shell puts on
  its caller, and the idiom for each.
- [Command reference](docs/reference.md) — every family and operation with its
  safety class.
- [Releasing](docs/releasing.md) — 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

```console
$ 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](LICENSE).
