Your first command line session#

In this tutorial, we will manage a Plone site from the terminal. We will look around a public demo site, start a site of our own, create and publish a page, and publish a batch of news items after previewing the change. At the end, you will have a profile for your site, and a script that reacts to what the command line reports.

You need uv and, for the second half, Docker and jq.

Install the command line#

Install plone-client as a tool.

uv tool install "plone-client[cli]"

Look at a site before you own one#

The demo site is a public Plone site at https://demo.plone.org. It is shared with other visitors and resets every night, so what you see may differ from what is shown here.

A profile gives a site a name. Add one for the demo site, and make it read-only so that nothing we type can change the site.

plone-client profile add demo --url https://demo.plone.org --read-only --frontend-url https://demo.plone.org --secret none

--secret none says that this profile has no password, because we are reading as an anonymous visitor.

Ask who you are on that site.

plone-client -p demo info
{
  "profile": "demo",
  "url": "https://demo.plone.org",
  "authenticated": false,
  "username": null,
  "credentials_rejected": false,
  "read_only": true,
  "plone_version": "6.2.2"
}

Every command prints JSON like this. -p demo picks the profile for one command.

List what is at the site root. -f keeps only the keys you name, which keeps the output short.

plone-client -p demo ls / -f @id,title,review_state
[
  {
    "@id": "https://demo.plone.org/plone-foundation.png",
    "title": "Plone Foundation Logo",
    "review_state": null
  },
  {
    "@id": "https://demo.plone.org/images",
    "title": "Images",
    "review_state": "published"
  },
  {
    "@id": "https://demo.plone.org/block",
    "title": "Blocks",
    "review_state": "published"
  },
  {
    "@id": "https://demo.plone.org/content-types",
    "title": "Content Types",
    "review_state": "published"
  },
  {
    "@id": "https://demo.plone.org/vertical-spacing",
    "title": "Vertical Spacing",
    "review_state": "published"
  }
]

Notice review_state: it is the workflow state of each content item.

Search the whole site for three pages.

plone-client -p demo search -t Document --limit 3 -f @id,title
[
  {
    "@id": "https://demo.plone.org/block",
    "title": "Blocks"
  },
  {
    "@id": "https://demo.plone.org/block/block-accordion",
    "title": "Accordion"
  },
  {
    "@id": "https://demo.plone.org/block/button-block",
    "title": "Button"
  }
]

Now try to change something.

plone-client -p demo create / Document --title "Not today"
{
  "error": {
    "type": "PloneReadOnlyError",
    "message": "POST / refused: the client is read-only"
  }
}

The command line refused before sending anything, and exited with code 7. To write, we need a site of our own.

Start a Plone site#

We will use a throwaway site that runs in Docker, with sample content already in it. Get the Compose file and start the site.

curl -O https://raw.githubusercontent.com/plone/plone-client/main/docker-compose.yml
docker compose up --wait

Open http://localhost:3000 to see the site in your browser. Run a Plone site for testing explains what this file starts.

Add a profile#

This profile keeps its password in your operating system’s keyring.

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

When asked for the password, type admin. These credentials belong to the throwaway Compose site; never reuse them on a real site. --use makes tutorial the current profile, so the next commands use it without being told. --frontend-url names the Volto server, which knows the blocks of the site.

Check that it works.

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

Look at the content#

List the news of the sample site.

plone-client ls /news -f @id,title,review_state
[
  {
    "@id": "http://localhost:8080/Plone/news/release-6-2",
    "title": "Release 6.2 is out",
    "review_state": "published"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "title": "Release party in Brasília",
    "review_state": "private"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-notes-draft",
    "title": "Release notes draft",
    "review_state": "private"
  },
  {
    "@id": "http://localhost:8080/Plone/news/sprint-report",
    "title": "Sprint report",
    "review_state": "pending"
  },
  {
    "@id": "http://localhost:8080/Plone/news/old-announcement",
    "title": "Old announcement",
    "review_state": "published"
  }
]

Two news items are private, one waits for review, and two are published.

Search does the same across the whole site. -t names a content type, and --state a workflow state.

plone-client search -t "News Item" --state pending -f @id,title
[
  {
    "@id": "http://localhost:8080/Plone/news/sprint-report",
    "title": "Sprint report"
  }
]

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": "9b1ae9466ba44daf9691b0b933f5b7c8",
  "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
{
  "state": {
    "id": "private",
    "title": "Private"
  },
  "transitions": [
    "publish",
    "submit"
  ]
}

Then run one.

plone-client workflow /hello publish -f review_state
{
  "review_state": "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. The page is still there.

plone-client get /hello -f title,review_state
{
  "title": "Hello, Plone",
  "review_state": "published"
}

Publish a batch of news#

Now the real job: publish every private news item at once, and look before we leap.

Find them, and keep their addresses in a file. -c prints JSON on one line, and jq takes the @id of each result.

plone-client search /news -t "News Item" --state private -c -f @id | jq -r '.[]."@id"' > drafts.txt
cat drafts.txt
http://localhost:8080/Plone/news/release-party
http://localhost:8080/Plone/news/release-notes-draft

Run the transition on each one with -n first.

xargs -I{} plone-client -c -n workflow {} publish < drafts.txt
{"dry_run": true, "method": "POST", "url": "http://localhost:8080/Plone/++api++/news/release-party/@workflow/publish"}
{"dry_run": true, "method": "POST", "url": "http://localhost:8080/Plone/++api++/news/release-notes-draft/@workflow/publish"}

These are the two requests that would go out, and they look right. Run the same line without -n.

xargs -I{} plone-client -c workflow {} publish -f review_state < drafts.txt
{"review_state": "published"}
{"review_state": "published"}

Count what is left.

plone-client search /news -t "News Item" --state private --count
{
  "items_total": 0
}

React to what happened#

Each kind of failure has its own exit code, so a script can tell them apart. Ask for something that does not exist.

plone-client get /news/missing -f title
case $? in
  0) echo "Found it." ;;
  5) echo "No such item, so we create it." ;;
  *) echo "Something else went wrong." ;;
esac
{
  "error": {
    "status_code": 404,
    "type": "NotFound",
    "message": "Resource not found: http://localhost:8080/Plone/++api++/news/missing",
    "method": "GET",
    "url": "http://localhost:8080/Plone/++api++/news/missing"
  }
}
No such item, so we create it.

Errors are JSON on standard error, and the code 5 means not found. Command line lists every code.

Clean up#

Delete the page, remove the profiles, and throw the site away.

plone-client delete /hello --yes
plone-client profile remove tutorial
{
  "deleted": [
    "/hello"
  ],
  "dry_run": false
}
{
  "removed": "tutorial",
  "secret_removed": true
}
plone-client profile remove demo
docker compose down -v

If a step failed, docker compose down -v still resets the site, and plone-client profile remove NAME removes each profile you added, demo and tutorial; then start again from the top.

You have explored a site without an account, added a profile, published a batch of items after previewing the change, and written a script that reacts to exit codes.

Next steps#