# CloudFormation CLI command reference
<a name="resource-type-cli"></a>

The following commands are available through the CloudFormation Command Line Interface (CLI).

**Topics**
+ [Global parameters](resource-type-cli-global-parameters.md)
+ [init](resource-type-cli-init.md)
+ [generate](resource-type-cli-generate.md)
+ [validate](resource-type-cli-validate.md)
+ [invoke](resource-type-cli-invoke.md)
+ [test](resource-type-cli-test.md)
+ [submit](resource-type-cli-submit.md)

# Global parameters
<a name="resource-type-cli-global-parameters"></a>

The following parameters can be used with any CloudFormation CLI command.

`-h`, `--help`

Shows the help message and exits.

`-v`, `--verbose`

Increase the output verbosity and can specify multiple times.

# init
<a name="resource-type-cli-init"></a>

## Description
<a name="resource-type-cli-init-description"></a>

The `init` command launches a wizard that walks you through setting up your project. Once your project is specified, the command generates a new extension project with stub source files.

While the specific folder structure and files generated varies project and by language, in general the project includes the following:
+ Schema file.
+ Handler function source files.
+ Unit test files.
+ Build files for the specified language.

By default, `init` generates the extension project in the current directory.

## Synopsis
<a name="resource-type-cli-init-synopsis"></a>

```
$ cfn init [--force]
```

## Options
<a name="resource-type-cli-init-options"></a>

`--force`

Force project files to be overwritten.

## Output
<a name="resource-type-cli-init-output"></a>

The `init` command launches a wizard that walks you through setting up the project, including specifying the extension name.

```
Initializing new project
Do you want to develop a new resource(r) or a module(m) or a hook(h)?
```

# generate
<a name="resource-type-cli-generate"></a>

## Description
<a name="resource-type-cli-generate-description"></a>

The `generate` command generates code based on the project and appropriate extension type schema.

## Synopsis
<a name="resource-type-cli-generate-synopsis"></a>

```
$ cfn generate
```

## Examples
<a name="resource-type-cli-generate-examples"></a>

The following command submits the resource to the registry in your CloudFormation account.

```
$ cfn generate && cfn submit --set-default --region us-east-1
```

## Output
<a name="resource-type-cli-generate-output"></a>

```
Generated files for <type_name>
```

# validate
<a name="resource-type-cli-validate"></a>

## Description
<a name="resource-type-cli-validate-description"></a>

Validates a project's specification against the appropriate extension schema.

## Synopsis
<a name="resource-type-cli-validate-synopsis"></a>

```
$ cfn validate
```

## Examples
<a name="resource-type-cli-validate-examples"></a>

The following command validates the extension type project.

```
$ cfn validate
```

# invoke
<a name="resource-type-cli-invoke"></a>

## Description
<a name="resource-type-cli-invoke-description"></a>

Performs contract tests on the specified handler of an extension type.

## Synopsis
<a name="resource-type-cli-invoke-synopsis"></a>

```
$ cfn invoke 
    [--endpoint <value>] 
    [--function-name <value>]
    [--region <value>]
    [--max-reinvoke <value>]
    action 
    request
```

## Options
<a name="resource-type-cli-invoke-options"></a>

`--endpoint <value>`

The endpoint at which the type can be invoked. Alternately, you can also specify an actual Lambda endpoint and function name in your AWS account.

Default: `http://127.0.0.1.3001`

`--function-name <value>`

The logical Lambda function name in the AWS SAM template. Alternately, you can also specify an actual Lambda endpoint and function name in your AWS account.

Default: `TypeFunction`

`--region <value>`

The region to configure the client to interact with.

Default: `us-east-1`

`--max-reinvoke <value>`

Maximum number of `IN_PROGRESS` re-invocations allowed before exiting. If not specified, will continue to re-invoke until terminal status is reached.

`action`

Which single handler to invoke.

Values: `CREATE` \$1 `READ` \$1 `UPDATE` \$1 `DELETE` \$1 `LIST`

`request`

File path to a JSON file containing the request with which to invoke the function.

# test
<a name="resource-type-cli-test"></a>

## Description
<a name="resource-type-cli-test-description"></a>

Performs contract tests on the handlers of an extension type.

## Synopsis
<a name="resource-type-cli-test-synopsis"></a>

```
$ cfn test 
    [--endpoint <value>] 
    [--function-name <value>]
    [--region <value>]
    [--role-arn <value>]
    [-- -k <value>]
    [-- --tb=<value>]
    [--enforce-timeout <value>]
```

## Options
<a name="resource-type-cli-test-options"></a>

`--endpoint <value>`

The endpoint at which the type can be invoked. Alternately, you can also specify an actual Lambda endpoint and function name in your AWS account.

Default: `http://127.0.0.1.3001`

`--function-name <value>`

The logical Lambda function name in the AWS SAM template. Alternately, you can also specify an actual Lambda endpoint and function name in your AWS account.

Default: `TestEntrypoint`

`--region <value>`

The region to use for temporary credentials.

Default: `us-east-1`

`--role-arn <value>`

The Amazon Resource Name (ARN) of the IAM execution role for the contract tests to assume and use when performing operations.

If you don't specify an execution role, the contract tests use the environment credentials or the credentials specified in the [Boto 3 credentials chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html).

`-- -k <value>`

Runs a single unit test. For more information, see [Using `-k expr` to select tests based on their name](https://doc.pytest.org/en/latest/example/markers.html#using-k-expr-to-select-tests-based-on-their-name) from the `pytest` documentation.

`-- --tb=<value>`

*Default*: `auto`

The following are valid values for the traceback. For more information, see [Modifying Python traceback printing](https://docs.pytest.org/en/6.2.x/usage.html#modifying-python-traceback-printing) from the `pytest` documentation.
+ *auto* – `long` tracebacks for the first and last entry, but `short` tracebacks for all other entries.
+ *long* – exhaustive and informative traceback formatting.
+ *short* – shorter traceback format.
+ *line* – only one line per failure.
+ *native* – standard library formatting.
+ *no* – no traceback.

`--enforce-timeout <value>`

Sets the read and list timeout to 60 seconds and the create, update, and delete handler timeouts to 120 seconds.

## Examples
<a name="resource-type-cli-test-examples"></a>

The following command performs contract tests on the handlers of the extension type.

```
$ cfn test
```

The following command runs one contract test at a time.

```
$ cfn test -- -k test-name
```

The following command increases the timeout time when running contract tests.

```
$ cfn test --enforce-timeout 60
```

The following command combines the contract test and timeout time.

```
$ cfn test --enforce-timeout 60 -- -k test-name
```

The following command starts a Lambda service and uses the test command to perform contract tests.

```
$ sam local start-lambda
$ cfn test -v --enforce-timeout 90
```

# submit
<a name="resource-type-cli-submit"></a>

## Description
<a name="resource-type-cli-submit-description"></a>

Registers the extension with CloudFormation, in the specified region. Registering a extension makes it available for use in CloudFormation operations.

Registering includes:
+ Validating the resource schema.
+ Packaging up the resource project files and uploading them to CloudFormation.

  This includes the source code for your resource handlers. These resource handlers run within the CloudFormation account.
+ Determining which handlers have been specified for the resource, and running the appropriate contract tests.
+ Uploading the resource handlers as functions that CloudFormation calls at the appropriate times in a resource's lifecycle.
+ Returning a *registration token* that you can use with the [DescribeTypeRegistration](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeTypeRegistration.html) action to track the status of the registration request.

**Note**  
The user registering the extension must be able to access the schema handler package in the Amazon S3 bucket. That is, the user needs to have [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) permissions for the schema handler package. For more information, see [Actions, Resources, and Condition Keys for Amazon S3](https://docs.aws.amazon.com/IAM/latest/UserGuide/list_amazons3.html) in the *AWS Identity and Access Management User Guide*.

## Synopsis
<a name="resource-type-cli-submit-synopsis"></a>

```
$ cfn submit
    [--dry-run]
    [--endpoint-url <value>]
    [--region <value>]
    [--role-arn <value>]
    [--no-role]
    [--set-default]
```

## Options
<a name="resource-type-cli-submit-options"></a>

`--dry-run`

Validate the schema and package up the project files, but doesn't register the extension with CloudFormation.

`--endpoint-url <value>`

The CloudFormation endpoint to use.

`--region <value>`

The AWS Region in which to register the extension. If no region is specified, the extension is registered in the default region.

`--role-arn <value>`

A specific IAM role to use when invoking handler operations.

If you don't specify an IAM role, the CloudFormation CLI attempts to create or update an execution role based on the execution role template derived from the extension type's schema, and then passes this execution role to CloudFormation. For more information, see [Accessing AWS APIs from a Resource Type](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole).

You can't specify both `--role-arn` and `--no-role` arguments.

`--no-role`

Prevent the CloudFormation CLI from passing an execution role to CloudFormation.

If your resource type calls AWS APIs in any of its handlers, you must either specify a role Amazon Resource Name (ARN), or have the CloudFormation CLI create or update an execution role and pass that execution role to CloudFormation. For more information, see [Accessing AWS APIs from a Resource Type](https://docs.aws.amazon.com/cloudformation-cli/latest/userguide/resource-type-develop.html#resource-type-develop-executionrole).

You can't specify both `--role-arn` and `--no-role` arguments.

`--set-default`

Upon successful registration of the type version, sets the current type version as the default version.

## Examples
<a name="resource-type-cli-submit-examples"></a>

The following command builds and packages your extension project without registering it.

```
$ cfn submit --dry-run
```

The following command registers your extension.

```
$ cfn submit --set-default
```

The following command registers your extension in the us-west-2 region.

```
$ cfn submit --region us-west-2
```

## Output
<a name="resource-type-cli-submit-output"></a>

Extension registration is an asynchronous operation. You can use the supplied registration token to track the progress of your extension registration request using the [DescribeTypeRegistration](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeTypeRegistration.html) operation of the CloudFormation API.

```
{‘ProgressStatus’: ‘COMPLETE’}
```