Variables let you store information got from expressions, literal values or a actions. To understand variables you’ll also want to read conditionals and loops.

Creating valid variable names

Variable names should be letters, numbers, and underscores. Variables should always start with a letter.

The use of underscore _ instead of hyphen - is encouraged.

foo and foo_name are good variable names.

Registering variables

Variables could be registered using the method register_variables. This method is part of the Recipe Runner Core and as arguments it expects a dictionary which maps keys (variable names) to values.

  - name: "Creating variables step"
      # Two variables will be created: "user_name" and "email"
      - register_variables:
          user_name: "john"
          email: ""
        register: my_variables

The method "register_variables" let you register variables and they will be available from that moment on.

Registering the result of an action

Sometimes, it is useful to execute an action and save the return value in a variable for use in later actions. In that case, register a variable is very useful:

  - name: "Current directory"
      - run: pwd
        # Register the result of the command "pwd" in a variable 
        # called "current_dir"
        register: current_dir
        # Display the current directory
      - write: "Current dir: {{registered['current_dir']['output']}}"

Accessing variable data

Once you've defined variables, you can use them in actions as argument of methods as well as part of loop and when expressions. Also variables are available for steps and they could be used as part of loop and when expressions.

When you create a variable, you are registering a variable in the execution context of the recipe. Registered variables are availables at registered key:

  - actions:
      - ask: "How are you? "
        register: "user_response"
      - write: "The Response was: {{registered['user_response']['response']}}"

The previous example is using a JSON notation to access the data. The ask method (see IO Module) stores the value typed by the user inside a response variable that is part of data stored at the variable registered.

As registered is an dictionary of data, variable data can be accessed using "dot" notation:

  - actions:
      - ask: "How are you? "
        register: "user_response"
      - write: "The Response was: {{registered.get('user_response.response')}}"

Dictionaries of data

Dictionaries are a data structure that exposes the following methods that could be part of an expression:


Returns the value at the end of the path using dot notation. This method admits a second parameters that set the default value in case the path cannot be resolved:

registered.get('myVariable.success', false)


Returns if the given key exists.

// or


Counts the number of item in the array.

// or

Common variables

Common variables are a set of read-only variables not created by the recipe that provides information about the environment in which the recipe is running.


(string) Returns the directory in which the recipe file is in.


(string) Returns the current working directory.


(string) The operating system family. Possible values: 'Windows', 'BSD', 'Darwin', 'Solaris', 'Linux' or 'Unknown'.


(string) Directory separator: / or \.


(string) Semicolon ; on Windows, colon : otherwise.


(string) The path of the temporary directory. E.g: /tmp or C:\Windows\Temp.


(string) The current PHP version following the patter major.minor.release[extra].