Get started#
By the end of this page, you will know what plone-client does, the few Plone words the rest of this documentation uses, and which path to follow. You need to know Python or a shell, and nothing about Plone.
Warning
plone-client is in alpha. Its Python API and its commands can change between releases; read the Changelog before you upgrade.
What plone-client is#
plone-client is one library with three ways in. The Python library talks to a site, the command line wraps the library for terminals and scripts, and the MCP server wraps it for AI assistants. All three use the same profiles and the same safety switches.
Plone in six words#
- Plone
A content management system. Plone stores content and decides who can see and change it.
- Volto
The website people see and edit. Volto is a React application that runs in front of Plone.
plone.restapiThe JSON API of Plone. Everything plone-client does goes through plone.restapi, so whatever you can do with plone-client, the API allows, and with the same permissions.
- Content type
The kind of an item, such as a page or a news item. A content type decides which fields the item has.
- Workflow
The life of an item, such as
privatethenpublished. A workflow decides who can see the item in each state, and a transition moves it from one state to the next.- Block
A piece of a page, such as a paragraph or an image. A Volto page is a list of blocks, stored as JSON on the item.
And one word of plone-client: a profile is a site with a name, such as production, whose password stays in your keyring.
The Glossary defines every other term.
What each interface can do#
You want to |
Library |
Command line |
MCP server |
|---|---|---|---|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
Yes |
|
Yes, with |
With |
Yes |
|
Yes |
Yes |
Yes |
|
Yes |
Yes |
With |
|
Yes |
Registry; the rest with |
With |
|
Yes |
With |
With |
|
Use several sites at once |
One client per site |
One profile per command |
One server |
Yes |
Yes |
Yes |
Yes means a dedicated method, command, or tool.
With request and with call_service mean the generic request: it reaches the same service with the same permissions, but you write the path and the body yourself.
Every cell is bounded by the permissions of the Plone user you log in as, and by the plone.restapi version of the site; see Compatibility.
Two sites you can use#
You can practice on two sites.
demo.plone.orgA public site with nothing to install. It is shared with other visitors and resets every night, so this documentation only reads from it.
- Your own, in Docker
A Compose site with Volto and sample content, which takes about a minute to start. Every tutorial step that changes something uses it; see Run a Plone site for testing.
Which versions work#
plone-client works with Plone 6.0, 6.1, and 6.2, and needs Python 3.11 or later. Compatibility lists the details.
Pick your path#
You want code that reads or changes a site.
You want commands that you type, or put in a script.
You want a model to do the editing, within limits.