Cumin CLI

Cumin CLI - Automation and orchestration framework written in Python

usage: cumin [-h] [-c CONFIG] [--global-timeout GLOBAL_TIMEOUT] [-t TIMEOUT]
             [-m {sync,async}] [-p PCT] [-b BATCH_SIZE] [-s BATCH_SLEEP] [-x]
             [-o {txt,json}] [-i] [-n] [--force] [--backend BACKEND]
             [--transport {clustershell}] [--dry-run] [--no-progress]
             [--version] [-d] [--trace]
             HOSTS_QUERY [COMMAND ...]

Positional Arguments


Hosts selection query


Command to be executed. If no commands are specified, --dry-run is set.

Named Arguments

-c, --config

configuration file. [default: /etc/cumin/config.yaml]


Global timeout in seconds (int) for the whole execution. [default: None (unlimited)]

-t, --timeout

Timeout in seconds (int) for the the execution of every command in each host. [default: None (unlimited)]

-m, --mode

Possible choices: sync, async

Execution mode, required when there are multiple COMMANDS to be executed. In sync mode, execute the first command on all hosts, then proceed with the next one only if -p/--success-percentage is reached. In async mode, execute on each host independently from each other, the list of commands, aborting the execution on any given host at the first command that fails.

-p, --success-percentage

Possible choices: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100

Percentage threshold to consider an execution unit successful. Required in sync mode, optional in async mode when -b/--batch-size is used. Accepted values are integers in the range 0-100. [default: 100]

-b, --batch-size

The commands will be executed with a sliding batch of this size. The batch mode depends on the -m/--mode option when multiple commands are specified. In sync mode the first command is executed in batch to all hosts before proceeding with the next one. In async mode all commands are executed on the first batch of hosts, proceeding with the next hosts as soon as one host completes all the commands. The -p/--success-percentage is checked before starting the execution in each host. It accept an absolute integer (i.e. 10) or a percentage (i.e. 50%). [default: None (# of hosts)]

-s, --batch-sleep

Sleep in seconds (float) to wait before starting the execution on the next host when -b/--batch-size is used. [default: None]

-x, --ignore-exit-codes

USE WITH CAUTION! Treat any executed command as successful, ignoring the exit codes. [default: False]

-o, --output

Possible choices: txt, json

Specify a different output format. [default: None]

-i, --interactive

Drop into a Python shell with the results. [default: False]

-n, --no-colors

Disable colored output. [default: False]


USE WITH CAUTION! Force the execution without confirmation of the affected hosts. [default: False]


Override the default backend selected in the configuration file for this execution. The backend-specific configuration must be already present in the configuration file. One of [direct, knownhosts, openstack, puppetdb] or any external backend listed in the configuration file [default: None]


Possible choices: clustershell

Override the default transport selected in the configuration file for this execution. The transport-specific configuration must already be present in the configuration file. [default: None]


Do not execute any command, just return the list of matching hosts and exit. [default: False]


Do not show the progress bars during execution.


show program's version number and exit

-d, --debug

Set log level to DEBUG. See also log_file in the configuration. [default: False]


Set log level to TRACE, a custom logging level intended for development debugging. See also log_file in the configuration. [default: False]

More details at