Scroll to navigation



puppet-lookup - Interactive Hiera lookup


Does Hiera lookups from the command line.

Since this command needs access to your Hiera data, make sure to run it on a node that has a copy of that data. This usually means logging into a Puppet Server node and running ´puppet lookup´ with sudo.

The most common version of this command is:

´puppet lookup KEY --node NAME --environment ENV --explain´


puppet lookup [--help] [--type TYPESTRING] [--merge first|unique|hash|deep] [--knock-out-prefix PREFIX-STRING] [--sort-merged-arrays] [--merge-hash-arrays] [--explain] [--environment ENV] [--default VALUE] [--node NODE-NAME] [--facts FILE] [--compile] [--render-as s|json|yaml|binary|msgpack] keys


The lookup command is a CLI for Puppet´s ´lookup()´ function. It searches your Hiera data and returns a value for the requested lookup key, so you can test and explore your data. It is a modern replacement for the ´hiera´ command.

Hiera usually relies on a node´s facts to locate the relevant data sources. By default, ´puppet lookup´ uses facts from the node you run the command on, but you can get data for any other node with the ´--node NAME´ option. If possible, the lookup command will use the requested node´s real stored facts from PuppetDB; if PuppetDB isn´t configured or you want to provide arbitrary fact values, you can pass alternate facts as a JSON or YAML file with ´--facts FILE´.

If you´re debugging your Hiera data and want to see where values are coming from, use the ´--explain´ option.

If ´--explain´ isn´t specified, lookup exits with 0 if a value was found and 1 otherwise. With ´--explain´, lookup always exits with 0 unless there is a major error.

You can provide multiple lookup keys to this command, but it only returns a value for the first found key, omitting the rest.

For more details about how Hiera works, see the Hiera documentation:


  • --help: Print this help message.
  • --explain Explain the details of how the lookup was performed and where the final value came from (or the reason no value was found).
  • --node NODE-NAME Specify which node to look up data for; defaults to the node where the command is run. Since Hiera´s purpose is to provide different values for different nodes (usually based on their facts), you´ll usually want to use some specific node´s facts to explore your data. If the node where you´re running this command is configured to talk to PuppetDB, the command will use the requested node´s most recent facts. Otherwise, you can override facts with the ´--facts´ option.
  • --facts FILE Specify a .json or .yaml file of key => value mappings to override the facts for this lookup. Any facts not specified in this file maintain their original value.
  • --environment ENV Like with most Puppet commands, you can specify an environment on the command line. This is important for lookup because different environments can have different Hiera data.
  • --merge first|unique|hash|deep: Specify the merge behavior, overriding any merge behavior from the data´s lookup_options. ´first´ returns the first value found. ´unique´ appends everything to a merged, deduplicated array. ´hash´ performs a simple hash merge by overwriting keys of lower lookup priority. ´deep´ performs a deep merge on values of Array and Hash type. There are additional options that can be used with ´deep´.
  • --knock-out-prefix PREFIX-STRING Can be used with the ´deep´ merge strategy. Specifies a prefix to indicate a value should be removed from the final result.
  • --sort-merged-arrays Can be used with the ´deep´ merge strategy. When this flag is used, all merged arrays are sorted.
  • --merge-hash-arrays Can be used with the ´deep´ merge strategy. When this flag is used, hashes WITHIN arrays are deep-merged with their counterparts by position.
  • --explain-options Explain whether a lookup_options hash affects this lookup, and how that hash was assembled. (lookup_options is how Hiera configures merge behavior in data.)
  • --default VALUE A value to return if Hiera can´t find a value in data. For emulating calls to the ´lookup()´ function that include a default.
  • --type TYPESTRING: Assert that the value has the specified type. For emulating calls to the ´lookup()´ function that include a data type.
  • --compile Perform a full catalog compilation prior to the lookup. If your hierarchy and data only use the $facts, $trusted, and $server_facts variables, you don´t need this option; however, if your Hiera configuration uses arbitrary variables set by a Puppet manifest, you might need this option to get accurate data. No catalog compilation takes place unless this flag is given.
  • --render-as s|json|yaml|binary|msgpack Specify the output format of the results; "s" means plain text. The default when producing a value is yaml and the default when producing an explanation is s.


To look up ´key_name´ using the Puppet Server node´s facts: $ puppet lookup key_name

To look up ´key_name´ with agent.local´s facts: $ puppet lookup --node agent.local key_name

To get the first value found for ´key_name_one´ and ´key_name_two´ with agent.local´s facts while merging values and knocking out the prefix ´foo´ while merging: $ puppet lookup --node agent.local --merge deep --knock-out-prefix foo key_name_one key_name_two

To lookup ´key_name´ with agent.local´s facts, and return a default value of ´bar´ if nothing was found: $ puppet lookup --node agent.local --default bar key_name

To see an explanation of how the value for ´key_name´ would be found, using agent.local´s facts: $ puppet lookup --node agent.local --explain key_name


Copyright (c) 2015 Puppet Inc., LLC Licensed under the Apache 2.0 License
June 2017 Puppet Labs, LLC