top of page
  • Akmod

Fine-tuning idem doc: A Power User's Guide

Have you ever felt like you're searching for a needle in a haystack when searching through documentation for a specific state? The "idem doc" subcommand is your best friend. Originally patterned after a similar capability in salt, this command is your inside scoop on any Idem state or function. Here's the nitty-gritty on its inception, capabilities, and some power-user tricks.

Purpose and Origins

You can use "idem doc" even if you don't have access to documentation. "idem doc" uses pop-tree under the hood to enumerate resources that were added to the hub -- so it is always up-to-date and accurate to the states available on your computer. idem doc was amped up during an innovation sprint for pyls-pop -- during that sprint we added line numbers and other details that made it so you could jump-to-references and use other handy IDE powers. You can also get json output from idem doc -- making it useful in automation for verifying the parameters available to a state and exposing parameters and their types/values to end users.

Leveraging JSON and jq

The most basic use case is to get the docs on a full reference:

idem doc

        Immediately return success

If you don't know the full reference to the function you need docs for, you can use a truncated version to list ALL the functions recursively under a ref. Since this output can be very long, we can use jq to shorten it to exactly what we want. Here is a command that lists all available present states on the hub and uses "--output=json" and jq to truncate the results to just the references:

idem doc states --output=json | jq -r '. | keys[] | select(. | endswith("present"))'

You could also narrow it down to just aws states.

idem doc --output=json | jq -r '. | keys[] | select(. | endswith("present"))'

You can also find all the "get" exec module functions available in idem-aws:

idem doc --output=json | jq -r '. | keys[] | select(. | endswith("get"))'


"idem doc" has morphed from a humble guide to an essential swiss-army knife for developers. Whether you need to automate tasks or just better understand what you're working with, it's got you covered.


bottom of page