CUMIN(1)

📦
version 5.1.1 · 2 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

💖 CUMIN(1) — the Cumin manual, but make it cute 💖

okay bestie, sit down, hydrate, because this is the Cumin manual page and it's lowkey iconic. Cumin is an automation and orchestration framework written in Python. That's the NAME section. That's it. That's the name. There's also the Cumin CLI — same thing, also an automation and orchestration framework written in Python, because the CLI is the whole vibe here. 🦋

Here's what calling it looks like, verbatim, no notes:

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 🎀

these are the ones you just... say. no dashes. just vibes.

  • HOSTS_QUERY — the hosts selection query. this is how you tell Cumin which hosts you're talking to. main character energy, honestly. 👑
  • COMMAND — the command you want executed. and bestie, listen: if you don't specify any commands at all, then --dry-run gets set. so it just... shows you the hosts and peaces out. no cap. ✨

🌸 NAMED ARGUMENTS 🌸

the flags. the icons. the ones with the dashes. let's go one by one because we respect every single one of them here. 💅

  • -c, --config — the configuration file. [default: /etc/cumin/config.yaml]
  • --global-timeout — global timeout in seconds (int) for the whole entire execution, start to finish. [default: None (unlimited)]
  • -t, --timeout — timeout in seconds (int) for the execution of every command in each host. [default: None (unlimited)]
  • -m, --mode — possible choices: sync, async.

the execution mode, and it's 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. fr fr, pick wisely. 🧚

  • -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

the 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 accepts 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] literally the fun one. 🐍
  • -n, --no-colors — disable colored output. [default: False] (sad, but valid)
  • --force — USE WITH CAUTION! Force the execution without confirmation of the affected hosts. [default: False]
  • --backend — override the default backend selected in the configuration file for this execution. The backend-specific configuration must already be present in the configuration file. One of [direct, knownhosts, openstack, puppetdb] or any external backend listed in the configuration file [default: None]
  • --transport — 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]

  • --dry-run — do not execute any command, just return the list of matching hosts and exit. [default: False] the "look but don't touch" of it all. 🙈
  • --no-progress — do not show the progress bars during execution. (we love progress bars tho)
  • --version — show program's version number and exit. ✨
  • -d, --debug — set log level to DEBUG. See also log_file in the configuration. [default: False]
  • --trace — 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 https://wikitech.wikimedia.org/wiki/Cumin — go read it, iykyk 🫶

👑 AUTHOR 👑

Riccardo Coccioli

2017-2020, Riccardo Coccioli <rcoccioli@wikimedia.org>, Wikimedia Foundation, Inc.

okay that's the whole page, bestie, every single flag accounted for, nothing skipped, we ate and left no crumbs 💅🍓

and a lil sign-off for the girlies who read all the way to the bottom: this whole thing is from Cumin 5.1.1, dated Mar 14, 2025. iconic. periodt. 💖✨

📦 where this page comes from