Everyday site management#

This guide collects recipes for jobs that come up on any Plone site. Each one names its goal, the commands, the output on the sample site, and how to verify and adapt it. The outputs follow from running the recipes in order, so an earlier recipe can change what a later one finds.

Before you start#

You need the command line, jq, and a profile. The examples run against the Compose site, whose sample content Run a Plone site for testing describes.

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

The password is admin, which belongs to the throwaway Compose site; never reuse it on a real site. If a command fails, look for its error in Troubleshoot.

Audit unpublished content#

Goal: list what visitors cannot see yet. Reads the site.

Prerequisites: a profile with a user who can see private items.

plone-client search --state private -f @id,title
plone-client search --state pending -f @id,title
[
  {
    "@id": "http://localhost:8080/Plone/about/team",
    "title": "Team"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "title": "Release party in Brasília"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-notes-draft",
    "title": "Release notes draft"
  }
]
[
  {
    "@id": "http://localhost:8080/Plone/news/sprint-report",
    "title": "Sprint report"
  }
]

Verify: count the same search.

plone-client search --state private -t "News Item" --count
{
  "items_total": 2
}

Adapt: drop -t to include every content type, or pass a path, such as search /news, to look inside one folder.

Find stale content#

Goal: list items that nobody changed after a date. Reads the site.

Prerequisites: none.

--index passes any catalog query. Every item of the sample site is older than the date below, so all five news items match.

plone-client search /news -t "News Item" -i 'modified:={"query": "2100-01-01", "range": "max"}' --sort-on modified -m modified -f @id,modified --limit 2
[
  {
    "@id": "http://localhost:8080/Plone/news/release-6-2",
    "modified": "2026-11-01T03:08:30+00:00"
  },
  {
    "@id": "http://localhost:8080/Plone/news/release-party",
    "modified": "2026-11-01T03:08:30+00:00"
  }
]

Verify: the modified date of each result is before the date you gave.

Adapt: change the date, or use "range": "min" for items changed after it. Raise --limit, which is 50 by default.

Publish in bulk#

Goal: publish the private items whose title starts with Release. Changes the site.

Prerequisites: a user who can publish.

Select the items with jq, and preview each transition with -n.

plone-client search /news -t "News Item" --state private -c -f @id,title | jq -r '.[] | select(.title | startswith("Release")) | ."@id"' > to-publish.txt
xargs -I{} plone-client -c -n workflow {} publish < to-publish.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"}

When the requests look right, run the same line without -n.

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

Verify: nothing private is left.

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

Adapt: pass --comment to record why in the history, or --effective to set the publication date. These lines look only in /news: search from / to cover the whole site. They use the current profile: with several sites, add -p NAME to each plone-client command. To publish a folder and everything inside it, use workflow /news publish --recursive.

Move a subtree and keep its old address#

Goal: archive an item without breaking links to it. Changes the site.

Prerequisites: a folder to move into.

plone-client create / Document --id archive --title Archive --publish publish -f @id,review_state
plone-client move /news/old-announcement --to /archive
{
  "@id": "http://localhost:8080/Plone/archive",
  "review_state": "published"
}
[
  {
    "source": "http://localhost:8080/Plone/news/old-announcement",
    "target": "http://localhost:8080/Plone/archive/old-announcement"
  }
]

Plone redirects the old path by itself. Add another alias if the item was known under a different address.

plone-client aliases add /archive/old-announcement /old-news | jq -c '[.items[].path]'
["/news/old-announcement","/old-news"]

Verify: list the aliases of the item in its new place.

plone-client aliases list /archive/old-announcement | jq '[.items[].path]'
[
  "/news/old-announcement",
  "/old-news"
]

Adapt: move takes several items, and a folder moves with everything inside it. copy takes the same options and leaves the original in place.

Reorder a folder#

Goal: put an item first in its folder, which is the order ls and menus show. Changes the site.

Prerequisites: none. The output assumes the previous recipe ran: it moved one item out of /news, so four are left.

plone-client order /news sprint-report top
[
  "http://localhost:8080/Plone/news/sprint-report",
  "http://localhost:8080/Plone/news/release-6-2",
  "http://localhost:8080/Plone/news/release-party",
  "http://localhost:8080/Plone/news/release-notes-draft"
]

Verify: ls shows the new order.

plone-client ls /news -f title -c
[{"title": "Sprint report"}, {"title": "Release 6.2 is out"}, {"title": "Release party in Brasília"}, {"title": "Release notes draft"}]

Adapt: the last argument takes top, bottom, up, down, or a number of positions, where -2 is two up.

Add users from a CSV file#

Goal: create accounts from a list, and put them in a group. Changes the site.

Prerequisites: a CSV file without a header line.

asmith,asmith@example.org,Ana Smith
bjones,bjones@example.org,Bo Jones

--no-send-reset skips the welcome email, which needs a mail server. Remove it on a site with one, so that each user gets a link to set a password.

while IFS=, read -r id email name; do
  plone-client users create "$id" --email "$email" --fullname "$name" --no-send-reset -d '{"password": "correct-horse-battery"}' -f id -c
  plone-client groups add-member editors "$id" -f items -c
done < people.csv
{"id": "asmith"}
{"items": ["asmith", "jdoe"]}
{"id": "bjones"}
{"items": ["asmith", "bjones", "jdoe"]}

Verify: list the members of the group.

plone-client users list --group editors -f id,fullname
[
  {
    "id": "asmith",
    "fullname": "Ana Smith"
  },
  {
    "id": "bjones",
    "fullname": "Bo Jones"
  },
  {
    "id": "jdoe",
    "fullname": "Jo Doe"
  }
]

Adapt: pass --role to users create for a global role. Give a group access to one folder with Manage users and sharing.

Compare a registry record across sites#

Goal: read one setting on every site you manage, and change it on one. Changes the site.

Prerequisites: a profile per site.

The second profile here is the same site, read-only, to stand in for production.

plone-client profile add production --url http://localhost:8080/Plone --username admin --secret env --read-only -c
{"name": "production", "url": "http://localhost:8080/Plone", "username": "admin", "secret": "env", "read_only": true, "current": false}
export PLONE_CLIENT_PASSWORD=admin
for profile in local production; do
  echo "$profile: $(plone-client -p "$profile" registry get plone.site_title)"
done
local: "Welcome to Plone 6"
production: "Welcome to Plone 6"

Change it on one site. The value is JSON, so a text needs its own quotes.

plone-client registry set plone.site_title '"Sample site"'
{
  "plone.site_title": "Sample site"
}

Verify: a read-only profile refuses the same change, with exit code 7.

plone-client -p production registry set plone.site_title '"Sample site"'
{
  "error": {
    "type": "PloneReadOnlyError",
    "message": "PATCH /@registry refused: the client is read-only"
  }
}

Adapt: registry list with a text finds the names of records.

Call a service without a command#

Goal: use a plone.restapi service or an add-on service that has no command. Changes the site.

Prerequisites: the service’s path, from its documentation. The site title in the output is the one the previous recipe set.

plone-client request GET /@site -f @id,plone.site_title
{
  "@id": "http://localhost:8080/Plone/@site",
  "plone.site_title": "Sample site"
}
plone-client request POST /news/release-6-2/@lock -d '{}' -f locked,stealable
plone-client request DELETE /news/release-6-2/@lock -f locked
{
  "locked": true,
  "stealable": true
}
{
  "locked": false
}

Verify: request GET /news/release-6-2/@lock shows the state of the lock.

Adapt: -P key=value adds query parameters, and -H 'Name: value' adds headers. Call other services does the same from Python.

Export metadata to CSV#

Goal: give someone a spreadsheet of the content. Reads the site.

Prerequisites: none. The states in the output assume the earlier recipes ran, which published the items whose title starts with Release.

-m asks the catalog for extra columns, and jq turns each result into a line.

plone-client search /news -t "News Item" --sort-on sortable_title -c -m review_state -f title,review_state | jq -r '.[] | [.title, .review_state] | @csv' > news.csv
cat news.csv
"Release 6.2 is out","published"
"Release notes draft","published"
"Release party in Brasília","published"
"Sprint report","pending"

Verify: the number of lines matches the count of the search.

wc -l < news.csv | tr -d ' '
4

Adapt: -m _all returns every catalog column. Raise --limit on a site with more than 50 matches.