psu/docs

Portainer Stack Utils Docs

CLI Commands

Table of contents

• Available actions
  • Aliased actions
• Available options
• Available environment variables
• Actions in details
  • deploy
  • rm
  • ls
  • status
  • services
  • tasks
  • tasks:healthy
  • containers
  • login
  • lint
  • inspect
  • system:info
  • actions
  • help
  • version
• Options in details
  • Stack environment variables
  • Verbose mode
  • Debug mode
  • Strict mode
  • Quiet mode
  • detect-job option
• Glossary
  • Job

Available actions

Name	Description
deploy	Deploy/update the given stack.
rm	Remove/undeploy the given stack.
ls	List stacks already deployed.
status	Check if the stack is running/deployed correctly.
services	List services already deployed in the current stack.
tasks	List tasks in the current stack.
tasks:healthy	List tasks who are running correctly in the current stack.
containers	List containers running in the current stack.
login	Log in to a Portainer instance.
lint	Validate the Docker compose/stack file.
inspect	Display low-level information of the current stack.
system:info	Display Docker system-wide information.
actions	List available actions for this program.
help	Display help message.
version	Display this program version.

Aliased actions

Aliased action	Equivalent action
auth	login
docker:info	system:info
list	ls
ps	tasks
ps:healthy	tasks:healthy
remove	rm
undeploy	rm
update	deploy
validate	lint

Available options

Flag	Option	Description	Used in action(s)
-l	--url=URL	URL of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-u	--user=USERNAME	Username of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-p	--password=PASSWORD	Password of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-n	--name=STACK_NAME	Stack name	deploy, rm, status, services, tasks, tasks:healthy, containers, inspect
-c, -f	--compose-file=FILE_PATH	Path to docker compose/stack file (required if action=deploy)	deploy, lint
-C, -F	--compose-file-base64=[BASE64]	Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy)	deploy, lint
-g	--env-file=[FILE_PATH]	Path to a file of environment variables, to be used by the stack (only used when action=deploy)	deploy
-G	--env-file-base64=[BASE64]	Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy)	deploy
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-r	--prune	Whether to prune unused containers or not (only used when action=deploy). Defaults to false	deploy
-T	--timeout=[SECONDS]	Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100	status, tasks, tasks:healthy
-j	--detect-job=[true|false]	Auto detect services who are jobs in the current stack. Defaults to true	status, tasks, tasks:healthy
-S	--service=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)	status, tasks, tasks:healthy, containers
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-v	--verbose	Increase the verbosity of messages. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false	ls, services, tasks, tasks:healthy, containers, inspect
-t	--strict	Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false	deploy, rm
-L	--lint=[true|false]	Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true	deploy
-h	--help	Display help message. To display help of a given action, run: psu <action> --help	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions, version
-V	--version	Display the version of this program
-s	--secure=[yes|no]	DEPRECATED: Use the --insecure option instead. Enable or disable the host's SSL certificate verification. Defaults to yes	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
-a	--action=[ACTION_NAME]	DEPRECATED: Use <action> argument instead. The name of the action to execute

Available environment variables

Environment variable	Description	Used in action(s)
ACTION=ACTION_NAME	The name of the action to execute	n/a
PORTAINER_URL=URL	URL of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_USER=USERNAME	Username of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_PASSWORD=PASSWORD	Password of the Portainer instance	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_AUTH_TOKEN=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_STACK_NAME=STACK_NAME	Stack name	deploy, rm, status, services, tasks, tasks:healthy, containers, inspect
DOCKER_COMPOSE_FILE=FILE_PATH	Path to docker compose/stack file (required if action=deploy)	deploy, lint
ENVIRONMENT_VARIABLES_FILE=[FILE_PATH]	Path to a file of environment variables, to be used by the stack (only used when action=deploy)	deploy
PORTAINER_ENDPOINT=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
PORTAINER_PRUNE=[true|false]	Whether to prune unused containers or not (only used when action=deploy). Defaults to false	deploy
TIMEOUT=[SECONDS]	Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100	status, tasks, tasks:healthy
AUTO_DETECT_JOB=[true|false]	Auto detect services who are jobs in the current stack. Defaults to true	status, tasks, tasks:healthy
PORTAINER_SERVICE_NAME=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)	status, tasks, tasks:healthy, containers
HTTPIE_VERIFY_SSL=[yes|no]	Enable or disable the host's SSL certificate verification. Defaults to yes	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
VERBOSE_MODE=[true|false]	Increase the verbosity of messages. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
DEBUG_MODE=[true|false]	Print as much information as possible to help diagnosing a malfunction. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, lint, inspect, system:info, actions
MASKED_VARIABLES=[true|extended|false]	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false	deploy, rm, ls, status, services, tasks, tasks:healthy, containers, login, inspect, system:info
QUIET_MODE=[true|false]	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false	ls, services, tasks, tasks:healthy, containers, inspect
STRICT_MODE=[true|false]	Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false	deploy, rm
DOCKER_COMPOSE_LINT=[true|false]	Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true	deploy

Actions in details

deploy

Deploy/update the given stack.

Aliased action:

update

Usage:

psu deploy [options]

Examples:

psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file /path/to/docker-compose.yml --env-file /path/to/env_vars_file

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name
-c, -f	--compose-file=FILE_PATH	Path to docker compose/stack file (required if action=deploy)

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-L	--lint=[true|false]	Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to true
-C, -F	--compose-file-base64=[BASE64]	Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy)
-g	--env-file=[FILE_PATH]	Path to a file of environment variables, to be used by the stack (only used when action=deploy)
-G	--env-file-base64=[BASE64]	Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy)
-r	--prune	Whether to prune unused containers or not (only used when action=deploy). Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-t	--strict	Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

rm

Remove/undeploy the given stack.

Aliased actions:

remove, undeploy

Usage:

psu rm [options]

Examples:

psu rm --user admin --password password --url https://portainer.local --name mystack

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-t	--strict	Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

ls

List stacks already deployed.

Aliased actions:

list

Usage:

psu ls [options]

Examples:

psu ls --user admin --password password --url https://portainer.local

Output a JSON array of the stacks already deployed:

[
  {
    "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Name": "mystack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
    "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
    "Env": [
      {
        "name": "MYSQL_ROOT_PASSWORD",
        "value": "password"
      }
    ]
  },
  {
    "Id": "mysecondstack_i0649w9uo9wtx1zesujpofkck",
    "Name": "mysecondstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "i0649w9uo9wtx1zesujpofkck",
    "ProjectPath": "/data/compose/mysecondstack_i0649w9uo9wtx1zesujpofkck"
  },
  {
    "Id": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "Name": "mythirdstack",
    "Type": "1",
    "EndpointID": "1",
    "EntryPoint": "docker-compose.yml",
    "SwarmID": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
    "ProjectPath": "/data/compose/mythirdstack_mythirdstack_w9uo9wtxi064ujpofkck91zes"
  },
]

With the quiet mode enabled:

psu ls --user admin --password password --url https://portainer.local --quiet

Output the name of the stacks already deployed:

mystack
mysecondstack
mythirdstack

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

status

Check if the stack is running/deployed correctly

If your stack has some services who acts as jobs, see the --detect-job option for more details.

This action is very useful in CI/CD pipelines, it's equivalent to the kubectl rollout status command of Kubernetes.

Usage:

psu status [options]

Examples:

psu status --user admin --password password --url https://portainer.local --name mystack

This command outputs nothing if the stack is correctly running or deployed.

It also has an exit code (or exit status). The exit code value return based on a command or program will successfully execute (return 0) or not (return 1 or higher).

psu status --user admin --password password --url https://portainer.local --name mystack --timeout 20

if [ $? -eq 0 ]; then
  echo "[OK] This stack is running/deployed correctly"
else
  echo "[ERROR] This stack isn't running/deployed correctly!"
fi

For more informations about exit code, you can read this article and this Wikipedia page

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-S	--service=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j	--detect-job=[true|false]	Auto detect services who are jobs in the current stack. Defaults to true
-T	--timeout=[SECONDS]	Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

services

List services already deployed in the current stack.

Usage:

psu services [options]

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

tasks

List tasks in the current stack.

If your stack has some services who acts as jobs, see the --detect-job option for more details.

Usage:

psu tasks [options]

Aliased action:

ps

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-S	--service=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j	--detect-job=[true|false]	Auto detect services who are jobs in the current stack. Defaults to true
-T	--timeout=[SECONDS]	Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

tasks:healthy

List tasks who are running correctly in the current stack.

If your stack has some services who acts as jobs, see the --detect-job option for more details.

Usage:

psu tasks:healthy [options]

Aliased action:

ps:healthy

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-S	--service=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-j	--detect-job=[true|false]	Auto detect services who are jobs in the current stack. Defaults to true
-T	--timeout=[SECONDS]	Timeout, number of seconds before thrown an error (only used when action=status|tasks|tasks:healthy). Defaults to 100
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

containers

List containers running in the current stack.

Usage:

psu containers [options]

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-S	--service=[SERVICE_NAME]	Filtering by a service name of the current stack (only used when action=status|tasks|tasks:healthy|containers)
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

login

Log in to a Portainer instance.

Usage:

psu login [options]

Aliased action:

auth

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance

Optional options:

Flag	Option	Description
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

lint

Validate the Docker compose/stack file.

Usage:

psu lint [options]

Aliased action:

validate

Required options:

Flag	Option	Description
-c, -f	--compose-file=FILE_PATH	Path to docker compose/stack file (required if action=deploy)

Optional options:

Flag	Option	Description
-C, -F	--compose-file-base64=[BASE64]	Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy)
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

inspect

Display low-level information of the current stack.

Usage:

psu inspect [options]

Examples:

psu inspect --user admin --password password --url https://portainer.local --name mystack

Output the JSON object of the stack if it's already deployed:

{
  "Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Name": "mystack",
  "Type": "1",
  "EndpointID": "1",
  "EntryPoint": "docker-compose.yml",
  "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
  "ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
  "Env": [
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "value": "password"
    }
  ]
}

With the quiet mode enabled:

psu inspect --user admin --password password --url https://portainer.local --name mystack --quiet

Output the stack name if it's already deployed:

mystack

Check if the stack is already deployed:

stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)

if [ -n "$stack_exist" ]; then
  echo OK
else
  echo KO
fi

## OR check the exit code of the last executed command:
stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)

status=$?
if $(exit $status); then
  echo OK
else
  echo KO
fi

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance
-n	--name=STACK_NAME	Stack name

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-q	--quiet	Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to false
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

system:info

Display Docker system-wide information.

Usage:

psu system:info [options]

Aliased action:

docker:info

Required options:

Flag	Option	Description
-l	--url=URL	URL of the Portainer instance
-u	--user=USERNAME	Username of the Portainer instance
-p	--password=PASSWORD	Password of the Portainer instance

Optional options:

Flag	Option	Description
-A	--auth-token=[AUTH_TOKEN]	Use a Portainer auth token instead of --user and --password options, you can get it with the psu login command. Defaults to null
-e	--endpoint=[ENDPOINT_ID]	Which Docker endpoint to use. Defaults to 1
-i	--insecure	Skip the host's SSL certificate verification, use at your own risk. Defaults to false
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-m	--masked-variables	In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true|extended|false. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

actions

List available actions for this program.

Optional options:

Flag	Option	Description
-v	--verbose	Increase the verbosity of messages. Defaults to false
-d	--debug	Print as much information as possible to help diagnosing a malfunction. Defaults to false
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

help

Display help message.

version

Display this program version.

Optional options:

Flag	Option	Description
-h	--help	Display help message. To display help of a given action, run: psu <action> --help

Options in details

Stack environment variables

There can be set environment variables for each stack, be it a new deployment or an update. For example:

touch .env
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
echo "ALLOWED_HOSTS=*" >> .env
psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file docker-compose.yml --env-file .env

Stack environment variables can be enabled through ENVIRONMENT_VARIABLES_FILE envvar or --env-file option or -g flag.

Verbose mode

In verbose mode the script prints execution steps.

Getting auth token...
Getting stack mystack...
Stack mystack not found.
Getting Docker info...
Getting swarm cluster (if any)...
Swarm cluster found.
Preparing stack JSON...
Creating stack mystack...

Verbose mode can be enabled through VERBOSE_MODE envvar or --verbose option or -v flag.

Debug mode

In debug mode the script prints as much information as possible to help diagnosing a malfunction.

WARNING: Debug mode will print configuration values (with Portainer credentials) and Portainer API responses (with sensitive information like authentication token and stacks environment variables). Avoid using debug mode in CI/CD pipelines, as pipeline logs are usually recorded.

Debug mode can be enabled through DEBUG_MODE envvar or --debug option or -d flag.

Strict mode

In strict mode the script never updates an existent stack nor removes an inexistent one, and instead exits with an error.

Strict mode can be enabled through STRICT_MODE envvar or --strict option or -t flag.

Quiet mode

In quiet mode the script prints the minimum of informations or nothing.

It's inspired by the --quiet option of docker images command.

Quiet mode can be enabled through QUIET_MODE envvar or --quiet option or -q flag.

detect-job option

The --detect-job option (true by default) detects if a service has a restart policy set to none and considered this service as a Job. If set to false, to considering a service as a Job, you need to set a container's label named job-name with the value you want (e.g. my-job-service-name) in the Docker compose/stack file.

See the Job definition section for more details.

Glossary

Job

Docker (or Portainer) doesn't have a true Job mechanism like Kubernetes.

But psu use an equivalent Docker behavior, based on filtering tasks status with a specific container's label (job-name). Or when, in your Docker compose/stack file, a service deploy.restart_policy.condition option is set to none.

The psu definition of a job is a Swarm service who ensures that all its specified task(s) successfully terminate.

Using a job is useful when you want to have a service who run a script (e.g. database migration). And shutdown this service when its script is successfully executed.

See the service named job in the docker-stack-web-app.yml file, for a real use case. It has both a container's label job-name and a restart policy set to none.