Your first command line session

Your first command line session#

In this tutorial, we will manage a Plone site from the terminal. We will add a profile for the site, look at its content, create and publish a page, and preview a change before making it.

You need uv and Docker.

Start a Plone site#

We will work against a throwaway Plone site running in Docker. Start it in its own terminal and leave it running.

docker run --rm -p 8080:8080 -e SITE=Plone -e TYPE=volto plone/plone-backend:6.1

Wait until the output shows Serving on http://0.0.0.0:8080. The site is now at http://localhost:8080/Plone, with the user admin and the password admin.

Install the command line#

In another terminal, install plone-client as a tool.

uv tool install "plone-client[cli]"

Add a profile#

A profile gives the site a name, and keeps its password in your operating system’s keyring.

plone-client profile add tutorial --url http://localhost:8080/Plone --username admin --use

When asked for the password, type admin. --use makes tutorial the current profile, so the next commands use it without being told.

Check that it works.

plone-client info

{
  "profile": "tutorial",
  "url": "http://localhost:8080/Plone",
  "authenticated": true,
  "username": "admin",
  "read_only": false,
  "plone_version": "6.1.5"
}

Every command prints JSON like this.

Look at the content#

List what is at the root of the site.

plone-client ls / -f @id,title,review_state

-f keeps only the keys you name, which keeps the output short. A new site has little content, so the list may be empty.

Create a page#

plone-client create / Document --id hello --title "Hello, Plone" --description "Created from the terminal"

{
  "@id": "http://localhost:8080/Plone/hello",
  "@type": "Document",
  "UID": "8a1c5a9d0bde4c6b9c3f1e2a7d6b5c4e",
  "id": "hello",
  "title": "Hello, Plone",
  "review_state": "private"
}

Your UID will differ. Notice that the page is private.

Publish it#

Ask which transitions the page has.

plone-client workflow /hello -f state,transitions

Then run one.

plone-client workflow /hello publish

Run plone-client ls / -f @id,title,review_state again, and you will see the page published.

Preview a change#

Before changing a site you care about, look at what a command would send. Add -n to delete the page without deleting it.

plone-client -n delete /hello

{
  "deleted": [
    "/hello"
  ],
  "dry_run": true
}

Nothing was sent. Run plone-client get /hello -f title to see that the page is still there.

Clean up#

Delete the page for real, and remove the profile and its password.

plone-client delete /hello --yes
plone-client profile remove tutorial

You have added a profile, read and changed a site, and previewed a change before making it. Stop the Plone site with Control-C in its terminal when you are done.

Next steps#

Contents