Ad-Hoc Commands and Your First Playbook

Ad-hoc commands: one task, no file

An ad-hoc command runs a single module against an inventory group, right from the command line — no playbook file needed. It's the right tool for a quick, one-off check, the same role Netmiko's send_command() played for a single read-only query.

terminal — per Ansible's documented behavior, not independently executed in this authoring environment

$ ansible switches -i inventory.yml -m cisco.ios.ios_facts --check
# gathers read-only facts from every host in the "switches" group

-m names the module to run; -i points at the inventory from Lesson 3. This particular example needs the cisco.ios collection and a real device (Option A) — ad-hoc commands aren't limited to localhost, but this specific one is.

Quick checkConcept check

What is an ad-hoc command best suited for?

A large, multi-step deployment with many tasksA quick, single-module task run directly from the command line, without writing a playbook fileRendering a Jinja2 templateInstalling the cisco.ios collection

Your first playbook: minimal, and genuinely runnable

A playbook is a YAML file describing one or more plays, each targeting a set of hosts and running a list of tasks. Here's the smallest complete one — no cisco.ios, no real device, nothing beyond ansible-core itself:

first_playbook.yml

- name: My first playbook
hosts: localhost
connection: local
gather_facts: false

tasks:
  - name: Confirm Ansible is working
    ansible.builtin.debug:
      msg: "Ansible is running this task"

hosts: localhost and connection: local mean this never leaves your machine — no inventory file, no network device, nothing but ansible-core. ansible.builtin.debug is one of the modules that ships with ansible-core itself; no collection required.

terminal — per Ansible's documented behavior, not independently executed in this authoring environment

$ ansible-playbook first_playbook.yml

PLAY [My first playbook] ******************************************

TASK [Confirm Ansible is working] ***********************************
ok: [localhost] => {
  "msg": "Ansible is running this task"
}

PLAY RECAP *************************************************************
localhost : ok=1 changed=0 unreachable=0 failed=0 skipped=0

This describes Ansible's own documented recap format. Run it yourself on Linux/macOS/WSL2 — this file needs nothing but ansible-core, so it's a genuine first thing to try on your own machine.

Quick checkIdentify the correct code

Which line makes the playbook above run entirely on your own machine, with no inventory file or network device involved?

gather_facts: falsehosts: localhost combined with connection: localname: My first playbookansible.builtin.debug

Valid YAML is not the same as a valid playbook

This is worth seeing directly, because it's an easy trap: YAML syntax rules and Ansible's own playbook rules are two separate things.

broken_playbook.yml — valid YAML, invalid playbook

- name: Broken playbook
hosts: localhost
tasks:
  - name: Missing module key
    msg: "this task has no module"

This file is syntactically correct YAML — indentation, colons, and dashes are all valid. But it isn't a valid Ansible task: every task needs a module key (like ansible.builtin.debug), and msg isn't one. Ansible would reject this at run time, not because the YAML is wrong, but because the playbook's shape is.

Two different kinds of 'wrong'

A YAML parser only checks indentation, colons, and structure — and the broken example above passes that check cleanly. Ansible's own schema check is a separate, second layer: does this task actually name a real module? ansible-playbook --syntax-check catches Ansible-specific problems that a plain YAML check never would.

Quick checkScenario

The broken_playbook.yml example above is checked with a plain YAML syntax validator. What does that check report?

A syntax error, because the task is missing a moduleNo error — the YAML itself is syntactically valid; the problem is that the task doesn't name a real Ansible module, which only Ansible's own playbook validation would catchAn error about the missing 'hosts' keyA syntax error about incorrect indentation

Quick checkMyth check

If a playbook file passes a plain YAML syntax check, is it guaranteed to be a valid, runnable Ansible playbook?

Yes — valid YAML always means a valid playbookNo — a playbook also has to follow Ansible's own schema (each task needs a real module, hosts needs a valid target, and so on), which a plain YAML check doesn't verifyYes, but only for playbooks targeting localhostNo, YAML syntax checking doesn't apply to Ansible files at all

Key takeaways

An ad-hoc command runs one module, once, with no playbook file — the right tool for a quick check.
A minimal playbook needs: a play (name, hosts), and at least one task naming a real module. hosts: localhost + connection: local means no inventory or network device required.
ansible.builtin.debug and other ansible.builtin.* modules ship with ansible-core itself — no collection needed for this lesson's examples.
Valid YAML syntax does not guarantee a valid Ansible playbook — verified directly: a task missing a module key parses as clean YAML but is not a runnable task.

What you'll learn

Ad-hoc commands: one task, no file

Your first playbook: minimal, and genuinely runnable

Valid YAML is not the same as a valid playbook