Link Search Menu Expand Document


Only for ~>1.* versions

Independent from how you install terraform-compliance, you need to provide some of the cli parameters.

[~] $ terraform-compliance -h

  terraform-compliance v1.0.0 initiated
  usage: terraform-compliance [-h] --features feature directory --planfile
                              plan_file [--identity [ssh private key]]
  BDD Test Framework for Hashicorp terraform
  optional arguments:
    -h, --help            show this help message and exit
    --features feature directory, -f feature directory
                          Directory (or git repository with 'git:' prefix)
                          consists of BDD features
    --planfile plan_file, -p plan_file
                          Plan output file generated by Terraform
    --identity [ssh private key], -i [ssh private key]
                          SSH Private key that will be use on git
    --terraform [terraform_file], -t [terraform_file]
                            The absolute path to the terraform executable.
    --version, -v         show program's version number and exit

CLI Reference

-f / –features


This parameter is used to provide feature files to terraform-compliance. It must be a directory or a git repository. All files within the directory (or repository) will be processed non-recursively.

[~] $ terraform-compliance -f /path/to/feature/files/ ...

or for a git repository ; (highly recommended for segregation of duties and having immutable features!)

If the repository is a public repository ;

[~] $ terraform-compliance -f git: ...

or if the repository is a private repository ;

[~] $ terraform-compliance -f git:ssh:// ...

The authentication to that git repository will be handled via your ~/.ssh/config. If you are using a different ssh key for this repository then you also need to provide -i parameter to pointing your private key.

New in 1.2.4, a repository can be referenced by branch name and directory. This uses syntax similar to Terraform Modules in Package Sub-directories. The reference must include // after .git and end with ?ref=<branch-name> or ?ref=<tag>.

[~] $ terraform-compliance -f git:ssh:// ...

The directory is optional.

[~] $ terraform-compliance -f git:ssh:// ...

-p / –planfile


terraform-compliance requires a plan or state output to run against. In order to create this plan file, you can run terraform ;

[~] $ terraform plan -out=plan.out

then you can provide this plan.out to terraform-compliance via ;

[~] $ terraform-compliance -p plan.out ...

terraform-compliance also supports parsing your state files. Your state file might be in your local, or in a remote entity. In order to download your state file ;

[~] $ terraform state pull > state.out

and then you can run your features against this state.out file via ;

[~] $ terraform-compliance -p state.out ...

-i / –identity


In case you need to authenticate to a private git repository as also described in -f parameter, then you may need to provide a private ssh key.

You can use -i parameter to do that ;

[~] $ terraform-compliance -i /path/to/ssh/private/key ...

Please note that, if the host that you are trying to authenticate already defined in ~/ssh/config, then terraform-compliance will use that key for authentication.

-t / –terraform


In some cases, a plan file that is created by a specific version of terraform might require the same version of that terraform in order to process that. terraform-compliance uses terraform in order to parse any plan/state files that has been created. In these cases you can just provide the same version of terraform via ;

[~] $ terraform-compliance -t /path/to/specific/versin/of/terraform ...

If you are using a Docker version of terraform-compliance, terraform binary is already packaged within the Docker Image. In case, you may need to use another version of terraform binary, you can still use -t to point the local version.

terraform executable is used to transform plan.out file produced from terraform plan to plan.out.json by running terraform show -json plan.out > plan.out.json. In case you are having version conflicts of terraform while using the Docker image of terraform-compliance, you can just avoid this problem and the need of terraform executable in your CI/CD container by running ;

[~] $ terraform plan -out plan.out                           # To create the plan
[~] $ terraform show -json plan.out > plan.out.json          # To convert the plan.out to JSON format just after the plan

-q / –quit-early



This option will disable default behaviour of terraform-compliance where the execution of the Scenario and Step (not Feature) will exit immediately upon first failure.

-n / –no-failures



This option will enforce to have 0 exit code independent of the test results. It is different than passing --wip since, that parameter only returns 0 if the test fails. This option will make terarform-compliance to report all errors, but always return 0 exit code.

-S / –silent



This option will surpress the output of Feature, Scenario and Steps. Only the summary and the Failure messages will be shown - if applicable.

-d / –debug



This option will let you peek in the stash or run IPython on the current step.


  • s: prints stash
  • d: opens Interactive Python.
  • h: prints commands

In Python shell, context can be accessed via step.context.stash. Note that modifications to step object will carry over to the steps below.

It is usually a better idea to inspect the stash before the step being debugged.

Table of contents

terraform-compliance made with . Distributed by an MIT license.