Command line#

plone-client is installed with the cli extra. Options of each command lists the arguments and options of every command, and plone-client <command> --help prints the same.

The examples on this page run against the Compose site, with the sample content of Run a Plone site for testing.

export PLONE_CLIENT_URL=http://localhost:8080/Plone
export PLONE_CLIENT_USERNAME=admin
export PLONE_CLIENT_PASSWORD=admin

Global options#

Option

Type

Required

Default

Description

--profile, -p

str

no

—

Profile to use.

--url

str

no

—

Site URL, instead of a profile; the password comes from $PLONE_CLIENT_PASSWORD.

--username, -u

str

no

—

Login name, with –url.

--config

file

no

—

Configuration file.

--read-only

flag

no

—

Refuse any change to the site.

--dry-run, -n

flag

no

—

Print the changes instead of sending them.

--fields, -f

str

no

—

Comma separated keys to keep in the output, such as ‘@id,title,review_state’.

--compact, -c

flag

no

—

Print JSON on one line.

--verbose, -v

flag

no

—

Log each request to stderr.

--version

flag

no

—

Show the version.

--install-completion

flag

no

—

Install completion for the current shell.

--show-completion

flag

no

—

Show completion for the current shell, to copy it or customize the installation.

-p, --config, -n, -f, -c, and -v work anywhere on the line. --url, -u, --read-only, and --version must come before the command, because profile add has options with the same names.

Commands#

plone-client --help lists the commands in the groups below, and each command group splits its subcommands into Browse (read only) and Write panels. In a terminal, the help draws each group as a box. When the output goes to a pipe or a file, as it does for scripts and coding agents, the help is plain text with the same groups as titled sections. To get plain help in a terminal too, set TYPER_USE_RICH=0.

<ref> accepts a path, a URL inside the site, uid:<UID>, or a resolveuid link.

Read content#

Command

Does

get

Print an item.

ls

List the items inside a folder, in order.

search

Search the catalog, inside a folder or the whole site.

resolve

Print the path, URL, and UID of an item.

blocks

Summarize the blocks of an item, nested ones included.

history

List the versions and workflow history of an item.

sharing

Show the local roles of an item.

Change content#

Command

Does

create

Create an item inside a folder.

create-page

Create a page from Markdown or HTML, converted to blocks; see Block types of converted pages. Needs the markdown extra.

create-with-files

Create an item, upload files and images inside it, and set its lead image.

update

Change fields of an item.

workflow

Show the workflow state and transitions of an item, or run a transition.

copy

Copy items into a folder.

move

Move items into a folder.

order

Move an item within its folder.

delete

Delete items.

Files#

Command

Does

upload

Upload files as File or Image items.

upload-tree

Upload the contents of a local folder as pages, files, and images, keeping its structure.

download

Download the file or image of an item.

Site users, settings, and types#

Command

Does

types

List content types, or show the JSON schema of one.

block-types

List the blocks of the site, or show the docs, schema, and variations of one.

vocabulary

List vocabularies, or the terms of one.

users

list, get / create, update, delete: browse and manage users.

groups

list, get / create, delete / add-member, remove-member: browse and manage groups and their members.

registry

list, get / set: browse and change registry records.

aliases

list / add, remove: browse and manage URL aliases.

Advanced#

Command

Does

request

Send any request, for services without a command.

mcp

Serve sites as an MCP server over standard input and output, or over HTTP; see MCP server. Needs the mcp extra.

mcp-token

generate, set, delete: manage the token clients send to mcp --http, kept in the keyring; see Over HTTP.

create-page, create-with-files, and upload-tree run the operations of plone_client.operations and print their result: created, changed, and every request in requests. When one of them stops part way, the error on standard error also has a result with what was already done, and the exit code is that of the request that failed.

Connection, profiles, and agents#

Command

Does

info

Show the profile, site, and user the command line connects with, and the Plone version. If the site rejected the profile’s credentials, the output has credentials_rejected: true and a message that names the fix, and the exit code is 4.

profile

list, show / add, use, defaults, remove / set-secret, test: manage connection profiles.

profile groups

groups / group-set, group-remove: list, create or replace, and remove groups of profiles; see Groups.

skill

show / install: print the agent skill, or install it.

In the group rows, / separates the panels of the group’s help: Browse, then Write, then Membership or Connection.

Options of each command#

aliases#

Browse, add, and remove URL aliases (redirects) of items.

Subcommands: add, list, remove.

aliases add#

Make old paths redirect to an item.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Item the aliases point to.

aliases

str

yes

—

Old paths.

aliases list#

List the aliases of an item, or every redirect of the site.

Argument or option

Type

Required

Default

Description

ref

str

no

/

Item; the site root lists every redirect.

--query

str

no

—

Filter, on the site root.

aliases remove#

Remove aliases.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Item the aliases point to.

aliases

str

yes

—

Alias paths.

block-types#

List the blocks of the site, or show one (Volto’s @blocks-schema).

Argument or option

Type

Required

Default

Description

block_id

str

no

—

Block whose docs, schema and variations to show.

--for

str

no

—

Only the blocks that editors can add to this item.

--markdown

flag

no

—

Print Markdown instead of JSON.

blocks#

Summarize the blocks of an item, nested ones included.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

--links

flag

no

—

List the links found in each block.

copy#

Copy items into a folder.

Argument or option

Type

Required

Default

Description

sources

str

yes

—

Items to copy.

--to

str

yes

—

Folder to copy into.

create#

Create an item inside a folder.

Argument or option

Type

Required

Default

Description

parent

str

yes

—

Path of the folder.

portal_type

str

yes

—

Content type, such as Document.

--title

str

no

—

Title.

--id

str

no

—

Id (short name).

--description

str

no

—

Description.

--data, -d

str

no

—

JSON object with field values; @file.json reads a file, - reads stdin.

--set, -s

str

no

—

Field value: key=text, or key:=json (subjects:=’[“a”]’). Repeatable.

--blocks, --no-blocks

flag

no

True

Add title and description blocks when no blocks are given.

--publish

str

no

—

Run this workflow transition after creating, e.g. publish.

--full

flag

no

—

Print the whole item, not a summary.

create-page#

Create a page from Markdown or HTML, converted to blocks.

Argument or option

Type

Required

Default

Description

parent

str

yes

—

Path of the folder.

source

str

yes

—

Markdown or HTML file; - reads standard input.

--html

flag

no

—

The source is HTML, not Markdown.

--title

str

no

—

Title; the leading # heading by default.

--description

str

no

—

Description.

--type, -t

str

no

Document

Content type, with blocks.

--id

str

no

—

Id (short name).

--data, -d

str

no

—

JSON object with field values; @file.json reads a file, - reads stdin.

--set, -s

str

no

—

Field value: key=text, or key:=json (subjects:=’[“a”]’). Repeatable.

--file

path

no

—

File or image to upload inside the page.

--lead

int range

no

—

Position of the lead image among the files, 1 for the first; the first image by default.

--no-lead

flag

no

—

Do not set a lead image.

--publish

str

no

—

Run this workflow transition at the end, e.g. publish.

--blocks

str

no

—

Block types to produce, as JSON, such as ‘{“codeBlock”: {“style”: “light”}, “slateTable”: false}’; merged over the profile’s.

create-with-files#

Create an item with files and images inside it, and set its lead image.

Argument or option

Type

Required

Default

Description

parent

str

yes

—

Path of the folder.

portal_type

str

yes

—

Content type, such as ‘News Item’.

files

path

yes

—

Files and images to upload inside the item.

--title

str

no

—

Title.

--description

str

no

—

Description.

--id

str

no

—

Id (short name).

--data, -d

str

no

—

JSON object with field values; @file.json reads a file, - reads stdin.

--set, -s

str

no

—

Field value: key=text, or key:=json (subjects:=’[“a”]’). Repeatable.

--lead

int range

no

—

Position of the lead image among the files, 1 for the first; the first image by default.

--no-lead

flag

no

—

Do not set a lead image.

--publish

str

no

—

Run this workflow transition at the end, e.g. publish.

delete#

Delete items.

Argument or option

Type

Required

Default

Description

refs

str

yes

—

Items to delete.

--yes, -y

flag

no

—

Do not ask.

download#

Download the file or image of an item.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

--output, -o

path

no

—

File to write; - for stdout.

--field

str

no

—

Field holding the file.

get#

Print an item.

Argument or option

Type

Required

Default

Description

ref

str

no

/

Path (/news/item), site URL, uid:<UID> or resolveuid link.

--expand

str

no

—

Component to expand: breadcrumbs, translations…

--fullobjects, --no-fullobjects

flag

no

—

Serialize contained items in full.

--items, --no-items

flag

no

True

Include the contained items.

--version

str

no

—

Version from the history.

groups#

Browse, create, and remove groups, and manage their members.

Subcommands: add-member, create, delete, get, list, remove-member.

groups add-member#

Add users to a group.

Argument or option

Type

Required

Default

Description

group_id

str

yes

—

Group id.

user_ids

str

yes

—

User ids.

groups create#

Create a group.

Argument or option

Type

Required

Default

Description

group_id

str

yes

—

Group id.

--title

str

no

—

Title.

--description

str

no

—

Description.

--role

str

no

—

Global role. Repeatable.

groups delete#

Delete a group.

Argument or option

Type

Required

Default

Description

group_id

str

yes

—

Group id.

--yes, -y

flag

no

—

Do not ask.

groups get#

Show a group and its members.

Argument or option

Type

Required

Default

Description

group_id

str

yes

—

Group id.

groups list#

List groups.

Argument or option

Type

Required

Default

Description

--query, -q

str

no

—

Text in the id.

groups remove-member#

Remove users from a group.

Argument or option

Type

Required

Default

Description

group_id

str

yes

—

Group id.

user_ids

str

yes

—

User ids.

history#

List the versions and workflow history of an item.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

info#

Show which site and user the client connects with.

ls#

List the items inside a folder, in order.

Argument or option

Type

Required

Default

Description

ref

str

no

/

Path (/news/item), site URL, uid:<UID> or resolveuid link.

--type, -t

str

no

—

Only this type.

--metadata, -m

str

no

—

Extra catalog column; _all for all.

--limit

int

no

100

Maximum number of items.

mcp#

Serve sites as an MCP server, over standard input and output or HTTP.

Argument or option

Type

Required

Default

Description

--site

str

no

—

Profile to serve; repeat it for several sites.

--group

str

no

—

Group of profiles to serve (see ‘profile groups’).

--all

flag

no

—

Serve every profile.

--tool

str

no

—

Offer only this tool; repeat it for several.

--http

flag

no

—

Serve over streamable HTTP, with a bearer token.

--host

str

no

127.0.0.1

Address to listen on, with –http.

--port

int

no

8000

Port to listen on, with –http.

mcp-token#

Manage the token MCP clients send to ‘plone-client mcp –http’.

Subcommands: delete, generate, set.

mcp-token delete#

Remove the token from the keyring.

mcp-token generate#

Make a new random token, store it in the keyring, and print it.

mcp-token set#

Store a token of your own in the keyring; it needs 32 characters.

Argument or option

Type

Required

Default

Description

--token-stdin

flag

no

—

Read the token from standard input.

move#

Move items into a folder.

Argument or option

Type

Required

Default

Description

sources

str

yes

—

Items to move.

--to

str

yes

—

Folder to move into.

order#

Move an item within its folder.

Argument or option

Type

Required

Default

Description

folder

str

yes

—

Path of the folder.

item_id

str

yes

—

Id of the item to move.

delta

str

yes

—

top, bottom, up, down, or a number of positions (-2 is two up).

profile#

Manage connection profiles; secrets are kept in the system keyring.

Subcommands: add, defaults, group-remove, group-set, groups, list, remove, set-secret, show, test, use.

profile add#

Add a profile, and store its secret in the keyring.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Profile name.

--url

str

yes

—

URL of the site root.

--username

str

no

—

Login name; empty for anonymous.

--auth

str

no

basic

One of basic, jwt, token.

--secret

str

no

keyring

Where the secret is: keyring, env, command, none.

--secret-env

str

no

PLONE_CLIENT_PASSWORD

Variable holding the secret, with –secret env.

--secret-command

str

no

—

Command printing the secret, with –secret command.

--read-only, --no-read-only

flag

no

—

Refuse changes to this site.

--transition

str

no

—

The only workflow transition run on this site; repeat it to allow more. Without it, every transition runs.

--timeout

float

no

—

Seconds to wait for the site.

--verify

str

no

—

Verify TLS certificates: true, false, or a CA bundle path.

--retries

int

no

—

Times a request is repeated after a network error.

--backoff

float

no

—

Base delay in seconds between retries.

--frontend-url

str

no

—

URL of the Volto frontend, when –url is the backend; used to list the site’s blocks.

--blocks

str

no

—

Block types that Markdown and HTML become on this site, as JSON, such as ‘{“codeBlock”: true}’.

--description

str

no

—

Free text.

--password-stdin

flag

no

—

Read the secret from standard input.

--use

flag

no

—

Make it the current profile.

--replace, --no-replace

flag

no

—

Replace an existing profile.

profile defaults#

Show or change the connection settings shared by every profile.

Argument or option

Type

Required

Default

Description

--timeout

float

no

—

Seconds to wait for the site.

--verify

str

no

—

Verify TLS certificates: true, false, or a CA bundle path.

--retries

int

no

—

Times a request is repeated after a network error.

--backoff

float

no

—

Base delay in seconds between retries.

--read-only, --read-write

flag

no

—

Refuse changes to every site.

--unset

str

no

—

Remove a setting: timeout, verify, retries, backoff, api_prefix, read_only.

profile group-remove#

Remove a group; its profiles are kept.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Group name.

profile group-set#

Create a group of profiles, or replace its profiles.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Group name.

profiles

str

yes

—

Profiles in the group.

profile groups#

List the groups of profiles.

profile list#

List the profiles; the current one is marked.

profile remove#

Remove a profile and its secret.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Profile name.

--keep-secret, --no-keep-secret

flag

no

—

Leave the secret in the keyring.

profile set-secret#

Store or replace the secret of a profile in the keyring.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Profile name.

--password-stdin

flag

no

—

Read the secret from standard input.

profile show#

Show the settings of a profile (never its secret).

Argument or option

Type

Required

Default

Description

name

str

no

—

Profile name; the current one by default.

profile test#

Connect with a profile and report who the client is logged in as.

Argument or option

Type

Required

Default

Description

name

str

no

—

Profile name; the current one by default.

profile use#

Make a profile the current one.

Argument or option

Type

Required

Default

Description

name

str

yes

—

Profile name.

registry#

Browse and change the site’s registry records.

Subcommands: get, list, set.

registry get#

Print the value of a record.

Argument or option

Type

Required

Default

Description

key

str

yes

—

Record name.

registry list#

List records with their values.

Argument or option

Type

Required

Default

Description

query

str

no

—

Text the record name must contain.

--limit

int

no

100

Maximum number of records.

registry set#

Change the value of a record.

Argument or option

Type

Required

Default

Description

key

str

yes

—

Record name.

value

str

yes

—

New value, as JSON (“text”, 10, true, [..]).

request#

Send any request to the site, for services without a command.

Argument or option

Type

Required

Default

Description

method

str

yes

—

GET, POST, PATCH, PUT or DELETE.

ref

str

yes

—

Path with the service, such as /news/@workflow.

--param, -P

str

no

—

Query parameter key=value. Repeatable.

--data, -d

str

no

—

JSON body; @file.json or - for stdin.

--header, -H

str

no

—

Header ‘Name: value’. Repeatable.

resolve#

Print the path, URL and UID of an item.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

sharing#

Show the local roles of an item.

Argument or option

Type

Required

Default

Description

ref

str

no

/

Path of the item.

--search

str

no

—

Also list users and groups matching this.

skill#

Show or install the agent skill that teaches coding agents this tool.

Subcommands: install, show.

skill install#

Install the skill, replacing an older copy.

Argument or option

Type

Required

Default

Description

--user

flag

no

—

Install in ~/.claude/skills, for every project.

--dir

path

no

—

Skills directory to install in; .claude/skills by default.

skill show#

Print the skill’s SKILL.md, or another file of the skill.

Argument or option

Type

Required

Default

Description

name

str

no

SKILL.md

File of the skill, such as references/blocks.md.

types#

List content types, or show the JSON schema of one.

Argument or option

Type

Required

Default

Description

portal_type

str

no

—

Type whose schema to show.

--addable-in

str

no

—

List only the types that can be added in this folder.

update#

Change fields of an item.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

--title

str

no

—

Title.

--description

str

no

—

Description.

--data, -d

str

no

—

JSON object with field values; @file.json reads a file, - reads stdin.

--set, -s

str

no

—

Field value: key=text, or key:=json (subjects:=’[“a”]’). Repeatable.

--lock-token

str

no

—

Token of a lock held on the item.

--full

flag

no

—

Print the whole item, not a summary.

upload#

Upload files as File or Image items.

Argument or option

Type

Required

Default

Description

parent

str

yes

—

Path of the folder.

files

file

yes

—

Files to upload.

--type, -t

str

no

—

Content type; Image or File by default.

--title

str

no

—

Title (one file only).

--id

str

no

—

Id (one file only).

--tus

flag

no

—

Send in chunks, for large files.

upload-tree#

Upload a local folder as pages, files and images, keeping its structure.

Argument or option

Type

Required

Default

Description

source

directory

yes

—

Local folder whose contents to upload.

parent

str

yes

—

Folder of the site to upload into.

--folder-type

str

no

Document

Content type for folders.

--pages

flag

no

—

Turn Markdown and HTML files into pages (needs the ‘markdown’ extra); index.md or README.md fills its folder’s page.

--hidden

flag

no

—

Also upload names starting with a dot.

--publish

str

no

—

Run this workflow transition at the end, e.g. publish.

--blocks

str

no

—

Block types to produce, as JSON, such as ‘{“codeBlock”: {“style”: “light”}, “slateTable”: false}’; merged over the profile’s.

users#

Browse, create, change, and remove users.

Subcommands: create, delete, get, list, update.

users create#

Create a user; by default the user gets an email to set the password.

Argument or option

Type

Required

Default

Description

username

str

yes

—

Login name.

--email

str

no

—

Email address.

--fullname

str

no

—

Full name.

--role

str

no

—

Global role. Repeatable.

--group

str

no

—

Group. Repeatable.

--send-reset, --no-send-reset

flag

no

True

Email the user a link to set the password.

--password-stdin

flag

no

—

Read the password from standard input.

--data, -d

str

no

—

More fields, JSON.

users delete#

Delete a user.

Argument or option

Type

Required

Default

Description

user_id

str

yes

—

User id.

--yes, -y

flag

no

—

Do not ask.

users get#

Show a user.

Argument or option

Type

Required

Default

Description

user_id

str

yes

—

User id.

users list#

List users.

Argument or option

Type

Required

Default

Description

--search, -q

str

no

—

Text in id, name or email.

--group

str

no

—

Only members of this group.

--limit

int

no

100

Maximum number of users.

users update#

Change a user; roles:=’{“Editor”: true}’ grants a role.

Argument or option

Type

Required

Default

Description

user_id

str

yes

—

User id.

--set, -s

str

no

—

Field: key=text or key:=json. Repeatable.

--data, -d

str

no

—

Fields, JSON.

vocabulary#

List vocabularies, or the terms of one.

Argument or option

Type

Required

Default

Description

name

str

no

—

Vocabulary name; without it, list the vocabularies.

--title

str

no

—

Filter terms by title.

--limit

int

no

100

Maximum number of terms.

workflow#

Show the workflow state of an item, or run a transition.

Argument or option

Type

Required

Default

Description

ref

str

yes

—

Path (/news/item), site URL, uid:<UID> or resolveuid link.

transition

str

no

—

Transition to run; without it, list the available ones.

--comment

str

no

—

Comment for the history.

--effective

str

no

—

Publication date, ISO 8601.

--expires

str

no

—

Expiration date, ISO 8601.

--recursive, --no-recursive

flag

no

—

Also run it on the items inside a folder.

Field values#

create and update merge field values from these options, each one winning over the previous.

Order

Option

Value

1

-d, --data

A JSON object, @file.json to read a file, or - to read standard input.

2

-s, --set, repeatable

key=text sets a string; key:=json sets any JSON value.

3

--title, --description

The title and the description.

create adds a title block and a description block to an item created without blocks, unless given --no-blocks.

Output#

Results are JSON on standard output, indented unless -c is given.

ls prints a list of items, each with its @id, its @type, and the columns of the catalog.

plone-client ls /about
[
  {
    "@id": "http://localhost:8080/Plone/about/team",
    "@type": "Document",
    "description": "The people behind the site.",
    "effective": "1969-12-31T00:00:00+00:00",
    "end": null,
    "getObjSize": "0 KB",
    "getRemoteUrl": null,
    "head_title": null,
    "image_field": "",
    "image_scales": null,
    "mime_type": "text/plain",
    "nav_title": null,
    "review_state": "private",
    "start": null,
    "title": "Team",
    "type_title": "Page"
  }
]

search prints the same list. --count prints only the total.

plone-client search -t Image -f @id,title,image_field
[
  {
    "@id": "http://localhost:8080/Plone/media/logo.png",
    "title": "Logo",
    "image_field": "image"
  }
]
plone-client search -t Image --count
{
  "items_total": 1
}

Commands that create or change an item print @id, @type, UID, id, title, and review_state.

plone-client update /about/team --description "The people behind the site"
{
  "@id": "http://localhost:8080/Plone/about/team",
  "@type": "Document",
  "UID": "d5ad47d7684449d4b73788eaa13d8b76",
  "id": "team",
  "title": "Team",
  "review_state": "private"
}

-f keeps the keys you name, and -c puts the result on one line.

plone-client update /about/team --description "The people behind the site" -f id,review_state -c
{"id": "team", "review_state": "private"}

--full prints the whole item, which has every field of its content type.

plone-client update /about/team --description "The people behind the site" --full -c | jq 'length'
39

-f keeps the listed keys of an item, of each item in a list, and of each entry in the items of a folder or a search. On an answer with items, as request returns, it applies to the answer itself as soon as one of the keys is at its top level. A key that is not there is left out without an error, and an entry with none of the keys prints as {}.

plone-client ls /about -f id -c
[{}]

ls and search results have no id key: use @id.

Errors and exit codes#

Errors are JSON on standard error.

plone-client get /missing
{
  "error": {
    "status_code": 404,
    "type": "NotFound",
    "message": "Resource not found: http://localhost:8080/Plone/++api++/missing",
    "method": "GET",
    "url": "http://localhost:8080/Plone/++api++/missing"
  }
}

Code

Meaning

0

Success.

1

Unexpected error, or a refused confirmation.

2

Invalid usage, invalid JSON, or a destructive command without --yes and without a terminal.

3

Configuration: unknown profile, missing secret, or no site configured.

4

Not authenticated, not allowed, or the item is locked. info and profile test exit with 4 when the site rejected the profile’s credentials.

5

Not found.

6

Invalid request or conflict.

7

Refused by --read-only or a read-only profile.

8

The site could not be reached.

9

Server error.

Confirmation#

delete, users delete, and groups delete ask for confirmation. Without a terminal they require --yes. With --dry-run they need neither.