Use the command line in scripts and CI#

This guide shows you how to run plone-client where there is no keyring and no terminal, such as a shell script, a container, or a continuous integration job.

The examples run against the Compose site; see Run a Plone site for testing.

Connect with environment variables#

Without a profile, the command line reads the site from PLONE_CLIENT_* variables.

export PLONE_CLIENT_URL=http://localhost:8080/Plone
export PLONE_CLIENT_USERNAME=admin
export PLONE_CLIENT_PASSWORD=admin
plone-client info -f profile,url,authenticated,username
{
  "profile": null,
  "url": "http://localhost:8080/Plone",
  "authenticated": true,
  "username": "admin"
}

Configuration lists every variable. A profile named with -p or $PLONE_CLIENT_PROFILE wins over $PLONE_CLIENT_URL.

--url and -u do the same for one command, and must come before the command name. The password still comes from $PLONE_CLIENT_PASSWORD.

unset PLONE_CLIENT_URL PLONE_CLIENT_USERNAME
plone-client --url http://localhost:8080/Plone -u admin info -f authenticated,username
{
  "authenticated": true,
  "username": "admin"
}

Use a profile without a keyring#

A container usually has no keyring. A profile with the default --secret keyring then stops with a traceback, whose last line names the problem, and exit code 1.

echo admin | plone-client profile add ci --url http://plone:8080/Plone --username admin --password-stdin
keyring.errors.NoKeyringError: No recommended backend was available. Install a recommended 3rd party backend package; or, install the keyrings.alt package if you want to use the non-recommended backends. See https://pypi.org/project/keyring for details.

Keep the secret in a variable instead, with --secret env.

unset PLONE_CLIENT_PASSWORD
plone-client profile add ci --url http://localhost:8080/Plone --username admin --secret env --use -c
{"name": "ci", "url": "http://localhost:8080/Plone", "username": "admin", "secret": "env", "current": true}

The profile stores the name of the variable, and never its value. Without the variable, the command stops with exit code 3.

plone-client info
{
  "error": {
    "type": "PloneConfigurationError",
    "message": "Profile 'ci': set $PLONE_CLIENT_PASSWORD"
  }
}

With the variable, it connects.

export PLONE_CLIENT_PASSWORD=admin
plone-client info -f profile,authenticated
{
  "profile": "ci",
  "authenticated": true
}

--secret-env picks another variable, and --secret command runs a command that prints the secret. See Manage profiles.

Pass secrets on standard input#

Commands that take a secret read it from standard input with a flag, so it stays out of the process list and the shell history.

printf '%s' "correct-horse-battery" | plone-client users create robot --email robot@example.org --no-send-reset --password-stdin -f id
{
  "id": "robot"
}

profile add, profile set-secret, and mcp-token set have the same kind of flag.

Answer confirmations in advance#

Confirmation needs a terminal. Without one, a destructive command refuses to run, and exits with code 2.

plone-client users delete robot
Delete user robot: pass --yes to confirm

Pass --yes when the script has made sure of what it deletes.

plone-client users delete robot --yes
{
  "deleted": "robot",
  "dry_run": false
}

Read the results#

-c prints each result on one line, which suits jq and logs. Errors go to standard error, so standard output stays clean.

total=$(plone-client search /news -t "News Item" --count -c | jq .items_total)
echo "$total news items"
5 news items

Act on exit codes#

Each failure has its own exit code. Retry what can pass on a second try, and stop on the rest.

#!/usr/bin/env bash
plone-client info -c > /dev/null
code=$?
case $code in
  0) echo "The site answers." ;;
  3) echo "Fix the configuration." ; exit 1 ;;
  4) echo "Fix the credentials." ; exit 1 ;;
  8 | 9) echo "The site is down: try again later." ; exit 75 ;;
  *) echo "Unexpected exit code $code." ; exit 1 ;;
esac
bash check-site.sh
The site answers.

Make a job unable to change a site#

For an audit, set PLONE_CLIENT_READ_ONLY, so that a mistake in the script cannot change anything. $PLONE_CLIENT_URL also wins over the current profile.

export PLONE_CLIENT_URL=http://localhost:8080/Plone PLONE_CLIENT_USERNAME=admin PLONE_CLIENT_READ_ONLY=true
plone-client delete /news/release-6-2 --yes
{
  "error": {
    "type": "PloneReadOnlyError",
    "message": "DELETE /news/release-6-2 refused: the client is read-only"
  }
}

Run an audit in GitHub Actions#

This job starts the sample site, and fails if any news item is waiting for review. To audit a real site, remove the steps that start it, set PLONE_CLIENT_URL, and take the password from a repository secret, as in ${{ secrets.PLONE_PASSWORD }}.

name: Content audit

on:
  workflow_dispatch:
  schedule:
    - cron: "0 6 * * 1"

jobs:
  audit:
    runs-on: ubuntu-latest
    env:
      PLONE_CLIENT_URL: http://localhost:8080/Plone
      PLONE_CLIENT_USERNAME: admin
      PLONE_CLIENT_PASSWORD: admin
      PLONE_CLIENT_READ_ONLY: "true"
    steps:
      - name: Install uv
        uses: astral-sh/setup-uv@v10.3.2

      - name: Install plone-client
        run: uv tool install "plone-client[cli]"

      - name: Start the sample site
        run: |
          curl -O https://raw.githubusercontent.com/plone/plone-client/main/docker-compose.yml
          docker compose up --wait

      - name: Check the connection
        run: plone-client info

      - name: Fail on items waiting for review
        run: |
          pending=$(plone-client search --state pending --count -c | jq .items_total)
          echo "$pending items waiting for review"
          test "$pending" -eq 0

The commands of the last two steps are the same as on your computer.

pending=$(plone-client search --state pending --count -c | jq .items_total)
echo "$pending items waiting for review"
1 items waiting for review