Portainer CLI cheatsheet

portainerctl is the official Portainer BE CLI. Installed at /opt/homebrew/bin/portainerctl on the workstation.

Setup

portainerctl config add-context \
  --name swarm \
  --url   "$PORTAINER_URL" \
  --token "$PORTAINER_API_TOKEN"
portainerctl config use-context swarm

Common commands

portainerctl system status
portainerctl env list
portainerctl stack list --env 1
portainerctl stack deploy-swarm --name <n> --env 1 --file docker-stack.yml
portainerctl stack delete <id> --env 1

Known quirks

portainerctl docker -- node ls fails

The docker subcommand has a bind-address parsing bug. Use the raw Docker API proxy instead:

curl -H "X-API-Key: $PORTAINER_API_TOKEN" \
  "$PORTAINER_URL/api/endpoints/1/docker/nodes"

BE vs CE

The CLI advertises Portainer BE 2.39.1; the server here is CE 2.33.6. Most commands work; BE-only ones (license, observability, edge-update, policy) do not apply.