Portainer Stack Utils Docs
CLI Commands
Table of contents
- [Available actions](#available-actions)
- [Aliased actions](#aliased-actions)
- [Available options](#available-options)
- [Available environment variables](#available-environment-variables)
- [Actions in details](#actions-in-details)
- [`deploy`](#deploy)
- [`rm`](#rm)
- [`ls`](#ls)
- [`status`](#status)
- [`services`](#services)
- [`tasks`](#tasks)
- [`tasks:healthy`](#taskshealthy)
- [`containers`](#containers)
- [`login`](#login)
- [`lint`](#lint)
- [`inspect`](#inspect)
- [`system:info`](#systeminfo)
- [`actions`](#actions)
- [`help`](#help)
- [`version`](#version)
- [Options in details](#options-in-details)
- [Stack environment variables](#stack-environment-variables)
- [Verbose mode](#verbose-mode)
- [Debug mode](#debug-mode)
- [Strict mode](#strict-mode)
- [Quiet mode](#quiet-mode)
## Available actions
| Name | Description |
| --------------------------------- | ----------- |
| [`deploy`](#deploy) | Deploy/update the given stack. |
| [`rm`](#rm) | Remove/undeploy the given stack. |
| [`ls`](#ls) | List stacks already deployed. |
| [`status`](#status) | Check if the stack is running/deployed correctly. |
| [`services`](#services) | List services already deployed in the current stack. |
| [`tasks`](#tasks) | List tasks in the current stack. |
| [`tasks:healthy`](#taskshealthy) | List tasks who are running correctly in the current stack. |
| [`containers`](#containers) | List containers running in the current stack. |
| [`login`](#login) | Log in to a Portainer instance. |
| [`lint`](#lint) | Validate the Docker compose/stack file. |
| [`inspect`](#inspect) | Display low-level information of the current stack. |
| [`system:info`](#systeminfo) | Display Docker system-wide information. |
| [`actions`](#actions) | List available actions for this program. |
| [`help`](#help) | Display help message. |
| [`version`](#version) | Display this program version. |
### Aliased actions
| Aliased action | Equivalent action |
| ------------------ | ---------------------------------- |
| `auth` | [`login`](#login) |
| `docker:info` | [`system:info`](#systeminfo) |
| `list` | [`ls`](#ls) |
| `ps` | [`tasks`](#tasks) |
| `ps:healthy` | [`tasks:healthy`](#taskshealthy) |
| `remove` | [`rm`](#rm) |
| `undeploy` | [`rm`](#rm) |
| `update` | [`deploy`](#deploy) |
| `validate` | [`lint`](#lint) |
## Available options
| Flag | Option | Description | Used in action(s) |
| -----------| -------------------------------- | ----------- | ----------------- |
| `-l` | `--url=URL` | URL of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-u` | `--user=USERNAME` | Username of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-p` | `--password=PASSWORD` | Password of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-n` | `--name=STACK_NAME` | Stack name | [deploy](#deploy), [rm](#rm), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
| `-c`, `-f` | `--compose-file=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) | [deploy](#deploy), [lint](#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](#deploy), [lint](#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](#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](#deploy) |
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-r` | `--prune` | Whether to prune unused containers or not (only used when action=deploy). Defaults to `false` | [deploy](#deploy) |
| `-T` | `--timeout=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
| `-j` | `--detect-job=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers) |
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` | [ls](#ls), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
| `-t` | `--strict` | Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to `false` | [deploy](#deploy), [rm](#rm) |
| `-L` | `--lint=[true\|false]` | Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to `true` | [deploy](#deploy) |
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu --help` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions), [version](#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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `-a` | `--action=[ACTION_NAME]` | **DEPRECATED**: Use `` 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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `PORTAINER_USER=USERNAME` | Username of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `PORTAINER_PASSWORD=PASSWORD` | Password of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `PORTAINER_STACK_NAME=STACK_NAME` | Stack name | [deploy](#deploy), [rm](#rm), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
| `DOCKER_COMPOSE_FILE=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) | [deploy](#deploy), [lint](#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](#deploy) |
| `PORTAINER_ENDPOINT=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `PORTAINER_PRUNE=[true\|false]` | Whether to prune unused containers or not (only used when action=deploy). Defaults to `false` | [deploy](#deploy) |
| `TIMEOUT=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
| `AUTO_DETECT_JOB=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
| `PORTAINER_SERVICE_NAME=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers) |
| `HTTPIE_VERIFY_SSL=[yes\|no]` | Enable or disable the host's SSL certificate verification. Defaults to `yes` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `VERBOSE_MODE=[true\|false]` | Increase the verbosity of messages. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
| `DEBUG_MODE=[true\|false]` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#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](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
| `QUIET_MODE=[true\|false]` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` | [ls](#ls), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#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](#deploy), [rm](#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](#deploy) |
## Actions in details
### `deploy`
Deploy/update the given stack.
#### Aliased action:
`update`
#### Usage:
`psu deploy [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 |
| `-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 --help` |
### `rm`
Remove/undeploy the given stack.
#### Aliased actions:
`remove`, `undeploy`
#### Usage:
`psu rm [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` |
| `-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 --help` |
### `ls`
List stacks already deployed.
#### Aliased actions:
`list`
#### Usage:
`psu ls [options]`
#### Examples:
```bash
psu ls --user admin --password password --url https://portainer.local
```
Output a JSON array of the stacks already deployed:
```json
[
{
"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**:
```bash
psu ls --user admin --password password --url https://portainer.local --quiet
```
Output the name of the stacks already deployed:
```bash
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 --help` |
### `status`
Check if the stack is running/deployed correctly
#### Usage:
`psu status [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) |
| `-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 --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 --help` |
### `tasks`
List tasks in the current stack.
#### 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 --help` |
### `tasks:healthy`
List tasks who are running correctly in the current stack.
#### 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 --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 --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 --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 --help` |
### `inspect`
Display low-level information of the current stack.
#### Usage:
`psu inspect [options]`
#### Examples:
```bash
psu inspect --user admin --password password --url https://portainer.local --name mystack
```
Output the JSON object of the stack if it's already deployed:
```json
{
"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**:
```bash
psu inspect --user admin --password password --url https://portainer.local --name mystack --quiet
```
Output the stack name if it's already deployed:
```bash
mystack
```
**Check if the stack is already deployed**:
```bash
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 --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 --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 --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 --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:
```bash
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.
```text
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`](https://docs.docker.com/engine/reference/commandline/images/#options) command.
Quiet mode can be enabled through `QUIET_MODE` envvar or `--quiet` option or `-q` flag.