Exec

The built-in plugin called exec allows you to execute shell commands from within your HCL configuration.

Have a question?

Check the FAQ to see if there's already an answer.

Configuration

None

Actions

Name	Description
exec_command	Execute a shell command

exec_command

The exec_command action allows you to execute a shell command.

Arguments

Argument	Description	Type	Required
command	The command to execute	string	Yes
dot_env_filename	Name of file for outputs	string	No

Outputs

Output	Description	Type
exit_code	The exit code of the command	number
dot_env	Outputs parsed from dot_env_filename above	map

Usage

plugin exec {}

stage "dev" {
  task "hello_world" {
    action "exec_command" {
      alias = "hello_exec"
      dot_env_filename = ".env"
      command = <<EOF
        echo "Hello, world!"
        echo "example_key=example_value" >> .env
      EOF
    }
    output "example_key" {
      value = this.action.hello_exec.outputs.dot_env.example_key
    }
  }
}

stage "stage-2" {
  task "get_outputs" {
    action "exec_command" {
      command = <<EOF
        echo "output value : ${pipeline.stage.dev.task.hello_world.outputs.example_key}"
      EOF
    }
  }
}

In this example, the exec plugin is used to execute the echo "Hello, world!" command. The output of this command will be

• the exit code of the command, which will be 0 if the command was successful.
• a map of any key-value pairs (strings) written to file .env in the first stage.

Frequently Asked Questions (FAQ)

How would I reference the output of this exec action in another?

Use task outputs to share data between tasks. Define an output in the producer task, then reference it using pipeline.stage.<STAGE>.task.<TASK>.outputs.<OUTPUT> in the consumer task.

Important: When referencing outputs from another task within the same stage, you must use dependencies to ensure the producer task completes first, since tasks within a stage execute in parallel by default:

Expand for an example

stage "example" {
  task "producer" {
    action "exec_command" {
      dot_env_filename = ".env"
      command = <<EOF
        echo "result=success" > .env
      EOF
    }
    output "result" {
      value = this.action.exec_command.outputs.dot_env.result
    }
  }

  task "consumer" {
    dependencies = ["producer"]  # Required for same-stage references
    action "exec_command" {
      command = <<EOF
        echo "Result: ${pipeline.stage.example.task.producer.outputs.result}"
      EOF
    }
  }
}

Cross-stage references do not require dependencies since stages execute sequentially.

How can I use a complex variable or output inside of an exec command?

Since the command argument only accepts a string type, you will need to convert the complex variable or output to a string before it can be used. The variable can be passed to the built-in jsonencode function to convert it to a string. For example, if you wanted to use the variable var.my_variable in an exec command, you would use jsonencode(var.my_variable) in the command argument.