# AWS CloudFormation Guard CLI parameters and command reference
<a name="cfn-guard-command-reference"></a>

The following global parameters and commands are available through the AWS CloudFormation Guard command line interface (CLI).

**Topics**
+ [Guard CLI global parameters](cfn-guard-global-parameters.md)
+ [parse-tree](cfn-guard-parse-tree.md)
+ [rulegen](cfn-guard-rulegen.md)
+ [test](cfn-guard-test.md)
+ [validate](cfn-guard-validate.md)

# Guard CLI global parameters
<a name="cfn-guard-global-parameters"></a>

You can use the following parameters with any AWS CloudFormation Guard CLI command.

`-h`, `--help`

Prints help information.

`-V`, `--version`

Prints version information.

# parse-tree
<a name="cfn-guard-parse-tree"></a>

Generates a parse tree for the AWS CloudFormation Guard rules defined in a rules file.

## Syntax
<a name="cfn-guard-parse-tree-synopsis"></a>

```
cfn-guard parse-tree 
--output <value>
--rules <value>
```

## Parameters
<a name="cfn-guard-parse-tree-flags"></a>

`-h`, `--help`

Prints help information.

`-p`, `--print-json`

Prints the output in JSON format.

`-y`, `--print-yaml`

Prints the output in YAML format.

`-V`, `--version`

Prints version information.

## Options
<a name="cfn-guard-parse-tree-options"></a>

`-o`, `--output`

Writes the generated tree to an output file.

`-r`, `--rules`

Provides a rules file.

## Examples
<a name="cfn-guard-parse-tree-examples"></a>

```
cfn-guard parse-tree --output output.json --rules rules.guard
```

# rulegen
<a name="cfn-guard-rulegen"></a>

Takes a JSON- or YAML-formatted AWS CloudFormation template file and autogenerates a set of AWS CloudFormation Guard rules that match the properties of the template resources. This command is a useful way to get started with rule writing or to create ready-to-use rules from known good templates.

## Syntax
<a name="cfn-guard-rulgen-synopsis"></a>

```
cfn-guard rulegen
--output <value>  
--template <value>
```

## Parameters
<a name="cfn-guard-rulegen-flags"></a>

`-h`, `--help`

Prints help information.

`-V`, `--version`

Prints version information.

## Options
<a name="cfn-guard-rulegen-options"></a>

`-o`, `--output`

Writes the generated rules to an output file. Given the potential for hundreds or even thousands of rules to emerge, we recommend using this option.

`-t`, `--template`

Provides the path to a CloudFormation template file in JSON or YAML format.

## Examples
<a name="cfn-guard-rulegen-examples"></a>

```
cfn-guard rulegen --output rules.guard --template template.json
```

# test
<a name="cfn-guard-test"></a>

Validates an AWS CloudFormation Guard rules file against a Guard unit testing file in JSON or YAML format to determine the success of individual rules.

## Syntax
<a name="cfn-guard-test-synopsis"></a>

```
cfn-guard test 
--rules-file <value>
--test-data <value>
```

## Parameters
<a name="cfn-guard-test-flags"></a>

`-a`, `--alphabetical`

Sort alphabetically inside a directory.

`-h`, `--help`

Prints help information.

`-m`, `--last-modified`

Sorts by last-modified times within a directory

`-V`, `--version`

Prints version information.

`-v`, `--verbose`

Increases the output verbosity. Can be specified multiple times.

The verbose output follows the structure of the Guard rules file. Every block in the rules file is a block in the verbose output. The top-most block is each rule. If there are `when` conditions against the rule, they appear as a sibling condition block.

## Options
<a name="cfn-guard-test-options"></a>

`-d`, `--dir`

Provide the root directory for rules.

`-o`, `--output-format`

Specify the format in which the output should be displayed.

*Default*: `single-line-summary`

*Allowed values*: `json` \$1 `yaml` \$1 `single-line-summary` \$1 `junit`

`-r`, `--rules-file`

Provides the name of a rules file.

`-t`, `--test-data`

Provides the name of a file or directory for data files in either JSON or YAML format.

## Examples
<a name="cfn-guard-test-examples"></a>

```
cfn-guard test --rules-file rules.guard --test-data example.json
```

## Output
<a name="cfn-guard-test-output"></a>

```
PASS|FAIL Expected Rule = rule_name, Status = SKIP|FAIL|PASS, Got Status = SKIP|FAIL|PASS
```

## See also
<a name="cfn-guard-test-see-also"></a>

[Testing Guard rules](testing-rules.md)

# validate
<a name="cfn-guard-validate"></a>

Validates data against AWS CloudFormation Guard rules to determine success or failure.

## Syntax
<a name="cfn-guard-validate-synopsis"></a>

```
cfn-guard validate
--data <value>
--output-format <value>
--rules <value>
--show-summary <value>
--type <value>
```

## Parameters
<a name="cfn-guard-validate-flags"></a>

`-a`, `--alphabetical`

Validates files in a directory that is ordered alphabetically.

`-h`, `--help`

Prints help information.

`-m`, `--last-modified`

Validates files in a directory that is ordered by last-modified times.

`-P`, `--payload`

Provide rules and data in the following JSON format via `stdin`:

```
{"rules":["<rules 1>", "<rules 2>", ...], "data":["<data 1>", "<data 2>", ...]}
```

For example:

```
{"data": ["{\"Resources\":{\"NewVolume\":{\"Type\":\"AWS::EC2::Volume\",\"Properties\":{\"Size\":500,\"Encrypted\":false,\"AvailabilityZone\":\"us-west-2b\"}},\"NewVolume2\":{\"Type\":\"AWS::EC2::Volume\",\"Properties\":{\"Size\":50,\"Encrypted\":false,\"AvailabilityZone\":\"us-west-2c\"}}},\"Parameters\":{\"InstanceName\":\"TestInstance\"}}","{\"Resources\":{\"NewVolume\":{\"Type\":\"AWS::EC2::Volume\",\"Properties\":{\"Size\":500,\"Encrypted\":false,\"AvailabilityZone\":\"us-west-2b\"}},\"NewVolume2\":{\"Type\":\"AWS::EC2::Volume\",\"Properties\":{\"Size\":50,\"Encrypted\":false,\"AvailabilityZone\":\"us-west-2c\"}}},\"Parameters\":{\"InstanceName\":\"TestInstance\"}}"], "rules" : [ "Parameters.InstanceName == \"TestInstance\"","Parameters.InstanceName == \"TestInstance\"" ]}
```

For "rules", specify a list of string version of rules files. For "data", specify a list of string version of data files.

When `--payload` is specified `--rules` and `--data` cannot be specified.

`-p`, `--print-json`

Prints the output in JSON format.

`-s`, `--show-clause-failures`

Shows clause failure including a summary.

`-V`, `--version`

Prints version information.

`-v`, `--verbose`

Increases the output verbosity. Can be specified multiple times.

`-z`, `--structured`

Prints out a list of structured and valid JSON/YAML. This argument conflicts with the following arguments: verbose, print-json, show-summary: all/fail/pass/skip, output-format: single-line-summary

## Options
<a name="cfn-guard-validate-options"></a>

`-d`, `--data` (string)

Provides a data file or directory of data files in JSON or YAML. Supports passing multiple values by using this option repeatedly.

Example: `--data template1.yaml --data ./data-dir1 --data template2.yaml`

For directory arguments such as `data-dir1` above, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template

If you specify the `--payload` flag, don't specify the `--data` option.

`-i`, `--input-parameters` (string)

Provides a parameter file or directory of parameter files in JSON or YAML that specifies any additional parameters to use along with data files to be used as a combined context. All the parameter files passed as input get merged and this combined context is again merged with each file passed as an argument for `data`. Due to this, every file is expected to contain mutually exclusive properties, without any overlap. Supports passing multiple values by using this option repeatedly.

For directory arguments, scanning is only supported for files with following extensions: .yaml, .yml, .json, .jsn, .template

`-o`, `--output-format` (string)

Specifies the format for the output.

*Default*: `single-line-summary`

*Allowed values*: `json` \$1 `yaml` \$1 `single-line-summary` \$1 `junit` \$1 `sarif`

`-r`, `--rules` (string)

Provides a rules file or a directory of rules files. Supports passing multiple values by using this option repeatedly.

Example: `--rules rule1.guard --rules ./rules-dir1 --rules rule2.guard`

For directory arguments such as `rules-dir1` above, scanning is only supported for files with following extensions: .guard, .ruleset

If you specify the `--payload` flag, do not specify the `--rules` option.

`--show-summary` (string)

Controls if the summary table needs to be displayed. `--show-summary fail` (default) or `--show-summary pass,fail` (only show rules that did pass/fail) or `--show-summary none` (to turn it off) or `--show-summary all` (to show all the rules that pass, fail or skip).

*Default*: `fail`

*Allowed values*: `none` \$1 `all` \$1 `pass` \$1 `fail` \$1 `skip`

`-t`, `--type` (string)

Provides the format of your input data. When you specify the input data type, Guard displays the logical names of CloudFormation template resources in the output. By default, Guard displays property paths and values, such as `Property [/Resources/vol2/Properties/Encrypted`.

*Allowed values*: `CFNTemplate`

## Example
<a name="cfn-guard-validate-examples"></a>

```
cfn-guard validate --data example.json --rules rules.guard
```

## Output
<a name="cfn-guard-validate-output"></a>

If Guard successfully validates the templates, the `validate` command returns an exit status of `0` (`$?` in bash). If Guard identifies a rule violation, the `validate` command returns a status report of the rules that failed.

```
example.json Status = FAIL
FAILED rules
rules.guard/policy_effect_is_deny    FAIL
---
Evaluation of rules rules.guard against data example.json 
--
Property [/path/to/Effect] in data [example.json] is not compliant with [policy_effect_is_deny] because provided value ["Allow"] did not match expected value ["Deny"]. Error Message [ Policy statement "Effect" must be "Deny".]
```

## See also
<a name="cfn-guard-validate-see-also"></a>
+ [Validating input data against Guard rules](validating-rules.md)
+ [Using input parameters with Guard rules](using-input-parameters.md)