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#
Everyday site management has recipes for the jobs you will do next.
Manage profiles keeps secrets in a password manager.
Use the command line in scripts and CI runs the command line without a terminal.
Your first script does the same from Python.
Troubleshoot helps when a command fails.