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

The 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 private then published. 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

Read, search, and list content

Yes

Yes

Yes

Create, change, move, copy, and delete content

Yes

Yes

Yes

Run workflow transitions

Yes

Yes

Yes

Create a page from Markdown or HTML

Yes

Yes

Yes

Create an item with files and a lead image

Yes

Yes

Yes

Upload a folder of documents

Yes

Yes

Yes

Edit single blocks of a page

Yes, with plone_client.blocks

With update

Yes

List the block types of a site

Yes

Yes

Yes

Manage users and groups

Yes

Yes

With call_service

Change the registry and control panels

Yes

Registry; the rest with request

With call_service

Call any other service

Yes

With request

With call_service

Use several sites at once

One client per site

One profile per command

One server

Refuse changes, or preview them

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

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

🐍 Script Plone from Python

You want code that reads or changes a site.

Script Plone from Python
💻 Manage sites from a terminal

You want commands that you type, or put in a script.

Manage sites from a terminal
🤖 Work with AI assistants

You want a model to do the editing, within limits.

Work with assistants and coding agents