Commands of a script
Every script is its own CLI: python site.py COMMAND, or imix site.py COMMAND for a script that imports nothing.
| Command | What it does |
|---|---|
show | list the files the script declares (the default) |
cat [PATH...] | print their contents |
generate [DEST] | write the playbook directory (default out), or a tar archive |
diff [DEST] | show what generate DEST would change |
run [PLAYBOOK] | build into a temp dir and run ansible-playbook |
container [PLAYBOOK] | the same, with ansible in a container |
install [DEST] | generate, then ansible-galaxy install into the tree |
lint | run the registered checks, then ansible-lint |
test [TARGET] | run molecule, ansible-test, or a role’s test playbook |
profiles | list the profiles the script mentions |
describe | list the stages, tags, groups and variables, and what each is for |
doctor | check this machine against the runtime requirements |
env | build (or reuse) an environment that meets them, with uv |
image | print the container image the script asks for |
Every command also takes --jsonl, before or after its name: see
Events. An option with a second, --no- form can be
a default in the settings, and that form undoes it
for one run.
cat#
python site.py cat [PATHS...] [OPTIONS]Print the contents of PATHS (default: every file).
| Option | Takes | What it does |
|---|---|---|
PATHS | array of string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
container#
python site.py container [PLAYBOOK] [OPTIONS]Run PLAYBOOK (default: site.yml) with ansible-playbook in a container.
The tree is built here and mounted into the image, which only has to have ansible: an execution environment will do. The image is –image, else the script’s container_image(), else its base’s.
| Option | Takes | What it does |
|---|---|---|
PLAYBOOK | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--become--no-become | boolean | Run operations with become. |
--check--no-check | boolean | ansible-playbook –check. |
--connection | string | Connection type. |
--diff--no-diff | boolean | ansible-playbook –diff. |
--dir | string | Build in this directory instead of a temporary one. |
--engine | podman | docker | What runs the container (default: podman, else docker). |
--extra-vars | array of string | Extra variables (repeatable). |
--image | string | The image to run ansible in (default: the script’s; see image). |
--install--no-install | boolean | Install galaxy requirements into the tree first. |
--inventory | string | Override the inventory. |
--keep--no-keep | boolean | Keep the temporary build directory. |
--limit | string | Limit to a host subset. |
--list-hosts | boolean | List matching hosts and exit. |
--list-tasks | boolean | List the tasks and exit. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--pull | missing | always | never | newer default "missing" | When to pull the image. |
--record | string | Also write the run’s events to FILE (JSONL), for imix replay; ansible’s output stays as it is. |
--skip-tags | string | Skip these tags. |
--start-at-task | string | Start at this task. |
--step | boolean | Confirm each task. |
--syntax-check | boolean | Only check the syntax. |
--tags | string | Only run these tags. |
--user | string | Connect as this user. |
--vault-password-file | string | Vault password file. |
--verbose | integer, repeatable | Pass -v to ansible (repeatable). |
describe#
python site.py describe [OPTIONS]Say what this script has, and what each is for: its stages, tags, groups and variables.
| Option | Takes | What it does |
|---|---|---|
--json | boolean | Write it as one JSON object, on one line. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
diff#
python site.py diff [DEST] [OPTIONS]Show what generate DEST would change on disk.
| Option | Takes | What it does |
|---|---|---|
DEST | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
doctor#
python site.py doctor [OPTIONS]Check this machine against the script’s runtime requirements.
| Option | Takes | What it does |
|---|---|---|
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
env#
python site.py env [OPTIONS]Build the environment the script’s requirements describe, with uv.
It holds ansible-core and the pip requirements, on the Python that
requires_python() asks for, installed from a hash-checked lock, and the
collections and roles requires_collection() and requires_role() ask for,
installed with its own ansible-galaxy. Prints its directory; run --env
(and install, lint, test, doctor) use it, and so does imix lsp.
| Option | Takes | What it does |
|---|---|---|
--dir | string | Build here instead of the cache (~/.cache/instamix/envs). |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--upgrade--no-upgrade | boolean | Resolve the requirements again instead of reusing the lock. |
generate#
python site.py generate [DEST] [OPTIONS]Write the playbook directory to DEST (default: out).
A DEST ending in .tar, .tar.gz/.tgz, .tar.bz2/.tbz2 or .tar.xz/.txz is written as a tar archive instead, and - writes one to stdout.
| Option | Takes | What it does |
|---|---|---|
DEST | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--compress | bz2 | gz | none | xz | Write a tar archive with this compression, whatever DEST is called (default: from the name; gz for -). |
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--force--no-force | boolean | Write into a non-empty directory instamix did not create. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
image#
python site.py image [OPTIONS]Print the container image the script asks for (exit 1 when none): its container_image(), else its base’s.
| Option | Takes | What it does |
|---|---|---|
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
install#
python site.py install [DEST] [OPTIONS]Generate into DEST and install galaxy roles and collections there.
| Option | Takes | What it does |
|---|---|---|
DEST | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--skip-requirements--no-skip-requirements | boolean | Run even if this machine lacks the script’s runtime requirements. |
lint#
python site.py lint [OPTIONS]Run the registered checks, then ansible-lint (or a syntax check).
| Option | Takes | What it does |
|---|---|---|
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--checks-only | boolean | Only run the registered checks. |
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--no-builtin-checks--builtin-checks | boolean | Skip instamix’s own structural checks. |
--no-checks--checks | boolean | Skip the registered checks. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--skip-requirements--no-skip-requirements | boolean | Run even if this machine lacks the script’s runtime requirements. |
profiles#
python site.py profiles [OPTIONS]List the profiles this script mentions.
| Option | Takes | What it does |
|---|---|---|
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
run#
python site.py run [PLAYBOOK] [OPTIONS] [-- ARGS]Run PLAYBOOK (default: site.yml) with ansible-playbook.
| Option | Takes | What it does |
|---|---|---|
PLAYBOOK | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--become--no-become | boolean | Run operations with become. |
--check--no-check | boolean | ansible-playbook –check. |
--connection | string | Connection type. |
--diff--no-diff | boolean | ansible-playbook –diff. |
--dir | string | Build in this directory instead of a temporary one. |
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--extra-vars | array of string | Extra variables (repeatable). |
--install--no-install | boolean | Install galaxy requirements into the tree first. |
--inventory | string | Override the inventory. |
--keep--no-keep | boolean | Keep the temporary build directory. |
--limit | string | Limit to a host subset. |
--list-hosts | boolean | List matching hosts and exit. |
--list-tasks | boolean | List the tasks and exit. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--record | string | Also write the run’s events to FILE (JSONL), for imix replay; ansible’s output stays as it is. |
--skip-requirements--no-skip-requirements | boolean | Run even if this machine lacks the script’s runtime requirements. |
--skip-tags | string | Skip these tags. |
--start-at-task | string | Start at this task. |
--step | boolean | Confirm each task. |
--syntax-check | boolean | Only check the syntax. |
--tags | string | Only run these tags. |
--user | string | Connect as this user. |
--vault-password-file | string | Vault password file. |
--verbose | integer, repeatable | Pass -v to ansible (repeatable). |
show#
python site.py show [OPTIONS]List the files this script declares (default).
| Option | Takes | What it does |
|---|---|---|
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
test#
python site.py test [TARGET] [OPTIONS]Run the declared tests: molecule, ansible-test, or a role test playbook.
| Option | Takes | What it does |
|---|---|---|
TARGET | string | An argument, by its place. |
--bare--no-bare | boolean | Do not add a default inventory and ansible.cfg. |
--dir | string | Build in this directory instead of a temporary one. |
--env--no-env | boolean | Run ansible from an environment built (or reused) with uv from the script’s requirements; see env. |
--install--no-install | boolean | Install galaxy requirements into the tree first. |
--keep--no-keep | boolean | Keep the build directory. |
--kind | sanity | units | integration default "sanity" | What ansible-test should run. |
--list | boolean | List what could be tested and exit. |
--outside-paths--no-outside-paths | boolean | Let the environment’s (–env) or the image’s (container) collections and roles count: the tree’s ansible.cfg names them after its own, and –install does not install them again. Off, only the tree’s count. |
--profile | array of string | Activate a profile (repeatable, comma-separated; ‘*’ for all). Read before the script runs, so it also steers what it declares. |
--runner | auto | molecule | ansible-test | playbook default "auto" | Force a runner instead of picking one. |
--skip-requirements--no-skip-requirements | boolean | Run even if this machine lacks the script’s runtime requirements. |