ansible-doc

With thousands of modules across ansible-core and the installed collections, the skill that matters is finding the right module and its exact arguments fast, and ansible-doc does that from the terminal without a browser. ansible-doc apt prints every parameter, its type, default, and choices, plus the return values and runnable examples.

It is the same reference the website renders, pinned to the exact version you have installed — which is the version that actually matters. The docs you read are the docs your control node runs, so an argument the page shows is an argument your plays can use.

The Command

ansible-doc <module> prints the full page for one module: parameters, return values, examples. ansible-doc -l lists every available module, and ansible-doc -l | grep service is how you discover that service, systemd, and service_facts all exist before guessing at a name.

That pairing — full page for the module you know, filtered list for the one you do not — covers most lookups. Searching the list for a keyword turns "I think there's a module for this" into the module's real name and the collection it lives in.

Reading the Parameter Table

Each parameter shows its type, whether it is required, its default, and its allowed choices. This is where you learn that apt takes state with choices present, absent, and latest, so you stop guessing argument names and read them.

Reading the table beats memory. The difference between a task that works and an Unsupported parameters error is usually one argument name you half-remembered, and the table has the exact spelling, type, and default in front of you.

Return Values

The doc lists exactly what the module returns — changed, stdout, dest, and module-specific keys — which is precisely what you register and branch on. Reading the return section before you write the dependent task saves the trial-and-error of discovering the key shape at run time.

This closes the loop with the module model: a later task branches on what the module emits, so knowing the return shape up front means you write the conditional once, correctly, instead of running the play to find out which key carries the value you need.

FQCN in the Docs

The doc header shows the fully-qualified collection name — ansible.builtin.apt, community.general.timezone. The short name works when the collection is installed, but the FQCN is what you write in production plays and what tells you which collection a module lives in.

A play written with short names breaks on a control node where the collection is not installed, with an error that points at the missing module rather than the missing dependency. The FQCN the doc shows makes that dependency explicit, so the failure mode becomes obvious or never happens.

The Examples Block

ansible-doc ends with copy-ready task examples that show the common argument combinations. Reading them is faster than assembling a task from the parameter table alone, especially for a module you are meeting for the first time and do not yet have a feel for.

The examples encode the idioms — which arguments usually appear together, what a realistic invocation looks like. You start from a working task and adjust it, rather than building one argument at a time and hoping the combination is valid.

Snippet and Plugin Docs

ansible-doc -s <module> prints a terse, paste-ready task stub with every argument commented, so you delete what you do not need rather than building the task from scratch. It is the fastest path from "I want to use this module" to a task skeleton in your playbook.

ansible-doc -t <type> documents lookup, filter, and inventory plugins too, not just modules. The same tool covers the whole plugin surface, so the reference habit you build for modules carries straight over to the plugins you met in Chapter 2 and the ones still ahead.