# AWS IoT Greengrass Development Kit Command-Line Interface The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides features that help you develop [custom Greengrass components](develop-greengrass-components.md). You can use the GDK CLI to create, build, and publish custom components. When you create a component repository with the GDK CLI, you can start from a template or a community component from the [Greengrass Software Catalog](greengrass-software-catalog.md). Then, you can choose a build system that packages files as ZIP archives, uses a Maven or Gradle build script, or runs a custom build command. After you create a component, you can use the GDK CLI to publish it to the AWS IoT Greengrass service, so you can use the AWS IoT Greengrass console or API to deploy the component to your Greengrass core devices. When you develop Greengrass components without the GDK CLI, you must update the version and artifact URIs in the [component recipe file](component-recipe-reference.md) each time you create a new version of the component. When you use the GDK CLI, it can automatically update the version and artifact URIs for you each time you publish a new version of the component. The GDK CLI is open source and available on GitHub. You can customize and extend the GDK CLI to meet your component development needs. We invite you to open issues and pull requests on the GitHub repository. You can find the GDK CLI source at the following link: [https://github.com/aws-greengrass/aws-greengrass-gdk-cli](https://github.com/aws-greengrass/aws-greengrass-gdk-cli). ## Prerequisites To install and use the Greengrass Development Kit CLI, you need the following: + An AWS account. If you don't have one, see [Set up an AWS account](setting-up.md#set-up-aws-account). + A Windows, macOS, or Unix-like development computer with an internet connection. + For GDK CLI version 1.1.0 or later, [Python](https://www.python.org/downloads/) 3.6 or later installed on your development computer. For GDK CLI version 1.0.0, [Python](https://www.python.org/downloads/) 3.8 or later installed on your development computer. + [Git](https://git-scm.com/) installed on your development computer. + AWS Command Line Interface (AWS CLI) installed and configured with credentials on your development computer. For more information, see [Installing, updating, and uninstalling the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) and [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*. **Note** If you use a Raspberry Pi or another 32-bit ARM device, install AWS CLI V1. AWS CLI V2 isn't available for 32-bit ARM devices. For more information, see [Installing, updating, and uninstalling the AWS CLI version 1](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv1.html). + To use the GDK CLI to publish components to the AWS IoT Greengrass service, you must have the following permissions: + `s3:CreateBucket` + `s3:GetBucketLocation` + `s3:PutObject` + `greengrass:CreateComponentVersion` + `greengrass:ListComponentVersions` + To use the GDK CLI to build a component whose artifacts exist in an S3 bucket and not in the local file system, you must have the following permissions: + `s3:ListBucket` This feature is available for GDK CLI v1.1.0 and later. ## Changelog The following table describes the changes in each version of the GDK CLI. For more information, see the [GDK CLI Releases page](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases) on GitHub. | **Version** | **Changes** | | --- | --- | | 1.6.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.6.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.6.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.5.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.4.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.3.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.3 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.2 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.1 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.2.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.1.0 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/greengrass/v2/developerguide/greengrass-development-kit-cli.html) | | 1.0.0 | Initial version. | # Install or update the AWS IoT Greengrass Development Kit Command-Line Interface The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) is built on Python, so you can use `pip` to install it on your development computer. **Tip** You can also install the GDK CLI in a Python virtual environments such as [venv](https://docs.python.org/3/library/venv.html#module-venv). For more information, see [Virtual Environments and Packages](https://docs.python.org/3/tutorial/venv.html) in the *Python 3 documentation*. **To install or update the GDK CLI** 1. Run the following command to install the latest version of the GDK CLI from its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli). ``` python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@v1.6.2 ``` **Note** To install a specific version of the GDK CLI, replace *versionTag* with the version tag to install. You can view version tags for the GDK CLI in its [GitHub repository](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/tags). ``` python3 -m pip install -U git+https://github.com/aws-greengrass/aws-greengrass-gdk-cli.git@versionTag ``` 1. Run the following command to verify that the GDK CLI installed successfully. ``` gdk --help ``` If the `gdk` command isn't found, add its folder to PATH. + On Linux devices, add `/home/MyUser/.local/bin` to PATH, and replace *MyUser* with the name of your user. + On Windows devices, add `PythonPath\\Scripts` to PATH, and replace *PythonPath* with the path to the Python folder on your device. You can now use the GDK CLI to create, build, and publish Greengrass components. For more information about how to use the GDK CLI, see [AWS IoT Greengrass Development Kit Command-Line Interface commands](greengrass-development-kit-cli-commands.md). # AWS IoT Greengrass Development Kit Command-Line Interface commands The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) provides a command line interface that you can use to create, build, and publish Greengrass components on your development computer. GDK CLI commands use the following format. ``` gdk [arguments] ``` When you [install the GDK CLI](install-greengrass-development-kit-cli.md), the installer adds `gdk` to the PATH so you can run the GDK CLI from the command line. You can use the following arguments with any command: + Use `-h` or `--help` for information about a GDK CLI command. + Use `-v` or `--version` to see what version of GDK CLI is installed. + Use `-d` or `--debug` to output verbose logs that you can use to debug the GDK CLI. This section describes the GDK CLI commands and provides examples for each command. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets. **Topics** + [component](greengrass-development-kit-cli-component.md) + [config](greengrass-development-kit-cli-config.md) + [test-e2e](greengrass-development-kit-cli-test.md) # component Use the `component` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to create, build, and publish custom Greengrass components. **Topics** + [init](#greengrass-development-kit-cli-component-init) + [build](#greengrass-development-kit-cli-component-build) + [publish](#greengrass-development-kit-cli-component-publish) + [list](#greengrass-development-kit-cli-component-list) ## init Initialize a Greengrass component folder from a component template or community component. The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates). **Note** If you use GDK CLI v1.0.0, you must run this command in an empty folder. The GDK CLI downloads the template or community component to the current folder. If you use GDK CLI v1.1.0 or later, you can specify the `--name` argument to specify the folder where the GDK CLI downloads the template or community component. If you use this argument, specify a folder that doesn't exist. The GDK CLI creates the folder for you. If you don't specify this argument, the GDK CLI uses the current folder, which must be empty. If the component uses the [zip build system](gdk-cli-configuration-file.md#gdk-cli-configuration-file-build-system), the GDK CLI zips certain files in the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is `HelloWorld`, the GDK CLI creates a zip file named `HelloWorld.zip`. In the component recipe, the zip artifact name must match the name of the component folder. If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters. If you initialize a template or community component that uses the zip build system to a folder with a different name than the template or component, you must change the zip artifact name in the component recipe. Update the `Artifacts` and `Lifecycle` definitions such that the zip file name matches the name of the component folder. The following example highlights the zip file name in the `Artifacts` and `Lifecycle` definitions. ``` { ... "Manifests": [ { "Platform": { "os": "all" }, "Artifacts": [ { "URI": "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip", "Unarchive": "ZIP" } ], "Lifecycle": { "Run": "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" } } ] } ``` ``` --- ... Manifests: - Platform: os: all Artifacts: - URI: "s3://BUCKET_NAME/COMPONENT_NAME/COMPONENT_VERSION/HelloWorld.zip" Unarchive: ZIP Lifecycle: Run: "python3 -u {artifacts:decompressedPath}/HelloWorld/main.py {configuration:/Message}" ``` **Synopsis** ``` $ gdk component init [--language] [--template] [--repository] [--name] ``` **Arguments (initialize from component template)** + `-l`, `--language` – The programming language to use for the template that you specify. You must specify either `--repository` or `--language` and `--template`. + `-t`, `--template` – The component template to use for a local component project. To view available templates, use the [list](#greengrass-development-kit-cli-component-list) command. You must specify either `--repository` or `--language` and `--template`. + `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you. This feature is available for GDK CLI v1.1.0 and later. **Arguments (initialize from community component)** + `-r`, `--repository` – The community component to check out into the local folder. To view available community components, use the [list](#greengrass-development-kit-cli-component-list) command. You must specify either `--repository` or `--language` and `--template`. + `-n`, `--name` – (Optional) The name of the local folder where the GDK CLI initializes the component. Specify a folder that doesn't exist. The GDK CLI creates the folder for you. This feature is available for GDK CLI v1.1.0 and later. **Output** The following example shows the output produced when you run this command to initialize a component folder from the Python Hello World template. ``` $ gdk component init -l python -t HelloWorld [2021-11-29 12:51:40] INFO - Initializing the project directory with a python component template - 'HelloWorld'. [2021-11-29 12:51:40] INFO - Fetching the component template 'HelloWorld-python' from Greengrass Software Catalog. ``` The following example shows the output produced when you run this command to initialize a component folder from a community component. ``` $ gdk component init -r aws-greengrass-labs-database-influxdb [2022-01-24 15:44:33] INFO - Initializing the project directory with a component from repository catalog - 'aws-greengrass-labs-database-influxdb'. [2022-01-24 15:44:33] INFO - Fetching the component repository 'aws-greengrass-labs-database-influxdb' from Greengrass Software Catalog. ``` ## build Build a component's source into a recipe and artifacts that you can publish to the AWS IoT Greengrass service. The GDK CLI runs the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists. When you run this command, the GDK CLI creates a recipe and artifacts in the `greengrass-build` folder in the component folder. The GDK CLI saves the recipe in the `greengrass-build/recipes` folder and saves the artifacts in the `greengrass-build/artifacts/componentName/componentVersion` folder. If you use GDK CLI v1.1.0 or later, the component recipe can specify artifacts that exist in an S3 bucket but not in the local component build folder. You can use this feature to reduce bandwidth usage when you develop components with large artifacts, such as machine learning models. After you build a component, you can do one of the following to test it on a Greengrass core device: + If you develop on a different device than where you run the AWS IoT Greengrass Core software, you must publish the component to deploy it to a Greengrass core device. Publish the component to the AWS IoT Greengrass service, and deploy it to the Greengrass core device. For more information, see the [publish](#greengrass-development-kit-cli-component-build) command and [Create deployments](create-deployments.md). + If you develop on the same device where you run the AWS IoT Greengrass Core software, you can publish the component to the AWS IoT Greengrass service to deploy, or you can create a local deployment to install and run the component. To create a local deployment, use the Greengrass CLI. For more information, see [Greengrass Command Line Interface](gg-cli.md) and [Test AWS IoT Greengrass components with local deployments](test-components.md). When you create the local deployment, specify `greengrass-build/recipes` as the recipes folder and `greengrass-build/artifacts` as the artifacts folder. **Synopsis** ``` $ gdk component build ``` **Arguments** None **Output** The following example shows the output produced when you run this command. ``` $ gdk component build [2021-11-29 13:18:49] INFO - Getting project configuration from gdk-config.json [2021-11-29 13:18:49] INFO - Found component recipe file 'recipe.yaml' in the project directory. [2021-11-29 13:18:49] INFO - Building the component 'com.example.PythonHelloWorld' with the given project configuration. [2021-11-29 13:18:49] INFO - Using 'zip' build system to build the component. [2021-11-29 13:18:49] WARNING - This component is identified as using 'zip' build system. If this is incorrect, please exit and specify custom build command in the 'gdk-config.json'. [2021-11-29 13:18:49] INFO - Zipping source code files of the component. [2021-11-29 13:18:49] INFO - Copying over the build artifacts to the greengrass component artifacts build folder. [2021-11-29 13:18:49] INFO - Updating artifact URIs in the recipe. [2021-11-29 13:18:49] INFO - Creating component recipe in 'C:\Users\MyUser\Documents\greengrass-components\python\HelloWorld\greengrass-build\recipes'. ``` ## publish Publish this component to the AWS IoT Greengrass service. This command uploads build artifacts to an S3 bucket, updates the artifact URI in the recipe, and creates a new version of component from the recipe. The GDK CLI uses the S3 bucket and AWS Region that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`. You must run this command in the same folder where the `gdk-config.json` file exists. If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist. If you use GDK CLI v1.2.0 or later, You can override the AWS Region specified in the GDK CLI configuration file using the `--region` parameter. You can also specify additional options using the `--options` parameter. For a list of available options, see [Greengrass Development Kit CLI configuration file](gdk-cli-configuration-file.md). When you run this command, the GDK CLI publishes the component with the version that you specify in the recipe. If you specify `NEXT_PATCH`, the GDK CLI uses the next patch version that doesn't already exist. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/). **Note** If you use GDK CLI v1.1.0 or later, when you run this command, the GDK CLI checks if the component is built. If the component isn't built, the GDK CLI [builds the component](#greengrass-development-kit-cli-component-build) before it publishes the component. **Synopsis** ``` $ gdk component publish [--bucket] [--region] [--options] ``` **Arguments** + `-b`, `--bucket` – (Optional) Specify the name of the S3 bucket where the GDK CLI publishes component artifacts. If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist. The GDK CLI creates the bucket if it doesn't exist. This feature is available for GDK CLI v1.1.0 and later. + `-r`, `--region` – (Optional) Specify the name of the AWS Region to when the component is created. This argument overrides the Region name in the GDK CLI configuration. This feature is available for GDK CLI v1.2.0 and later. + `-o`, `--options` (Optional) Specify a list of options for publishing a component. The argument must be a valid JSON string or a file path to a JSON file containing the publishing options. This argument overrides the options in the GDK CLI configuration. This feature is available for GDK CLI v1.2.0 and later. **Output** The following example shows the output produced when you run this command. ``` $ gdk component publish [2021-11-29 13:45:29] INFO - Getting project configuration from gdk-config.json [2021-11-29 13:45:29] INFO - Found component recipe file 'recipe.yaml' in the project directory. [2021-11-29 13:45:29] INFO - Found credentials in shared credentials file: ~/.aws/credentials [2021-11-29 13:45:30] INFO - Publishing the component 'com.example.PythonHelloWorld' with the given project configuration. [2021-11-29 13:45:30] INFO - No private version of the component 'com.example.PythonHelloWorld' exist in the account. Using '1.0.0' as the next version to create. [2021-11-29 13:45:30] INFO - Uploading the component built artifacts to s3 bucket. [2021-11-29 13:45:30] INFO - Uploading component artifacts to S3 bucket: {bucket}. If this is your first time using this bucket, add the 's3:GetObject' permission to each core device's token exchange role to allow it to download the component artifacts. For more information, see https://docs.aws.amazon.com/greengrass/v2/developerguide/device-service-role.html. [2021-11-29 13:45:30] INFO - Not creating an artifacts bucket as it already exists. [2021-11-29 13:45:30] INFO - Updating the component recipe com.example.PythonHelloWorld-1.0.0. [2021-11-29 13:45:30] INFO - Creating a new greengrass component com.example.PythonHelloWorld-1.0.0 [2021-11-29 13:45:30] INFO - Created private version '1.0.0' of the component in the account.'com.example.PythonHelloWorld'. ``` ## list Retrieve the list of available component templates and community components. The GDK CLI retrieves community components from the [Greengrass Software Catalog](greengrass-software-catalog.md) and component templates from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates). You can pass the output of this command to the [init](#greengrass-development-kit-cli-component-init) command to initialize component repositories from templates and community components. **Synopsis** ``` $ gdk component list [--template] [--repository] ``` **Arguments** + `-t`, `--template` – (Optional) Specify this argument to list available component templates. This command outputs the name and language of each template in the format `name-language`. For example, in `HelloWorld-python`, the template name is `HelloWorld` and the language is `python`. + `-r`, `--repository` – (Optional) Specify this argument to list available community component repositories. **Output** The following example shows the output produced when you run this command. ``` $ gdk component list --template [2021-11-29 12:29:04] INFO - Listing all the available component templates from Greengrass Software Catalog. [2021-11-29 12:29:04] INFO - Found '2' component templates to display. 1. HelloWorld-python 2. HelloWorld-java ``` # config Use the `config` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to modify the configuration for the GDK in the configuration file, `gdk-config.json`. **Topics** + [update](#greengrass-development-kit-cli-config-update) ## update Start an interactive prompt to modify fields within an existing GDK configuration file. **Synopsis** ``` $ gdk config update [--component] ``` **Arguments** + `-c`, `--component` – To update component-related fields in the `gdk-config.json` file. This argument is required since it is the only option. **Output** The following example shows the output produced when you run this command to configure a component. ``` $ gdk config update --component Current value of the REQUIRED component_name is (default: com.example.PythonHelloWorld): Current value of the REQUIRED author is (default: author): Current value of the REQUIRED version is (default: NEXT_PATCH): Do you want to change the build configurations? (y/n) Do you want to change the publish configurations? (y/n) [2023-09-26 10:19:48] INFO - Config file has been updated. Exiting... ``` # test-e2e Use the `test-e2e` command in the AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) to initialize, build, and run end-to-end test modules in the GDK project. **Topics** + [init](#greengrass-development-kit-cli-test-init) + [build](#greengrass-development-kit-cli-test-build) + [run](#greengrass-development-kit-cli-test-run) ## init Initialize an existing GDK CLI project with a testing module that uses Greengrass Testing Framework (GTF). By default, GDK CLI retrieves the maven module template from the [AWS IoT Greengrass Component Templates repository on GitHub](https://github.com/aws-greengrass/aws-greengrass-component-templates). This maven module comes with a dependency on the `aws-greengrass-testing-standalone` JAR file. This command creates a new directory called `gg-e2e-tests` inside of the GDK project. If the testing module directory already exists and is not empty, the command exits without doing anything. This `gg-e2e-tests` folder contains the Cucumber feature and step definitions structured in a maven project. By default, this command will try to use the latest release version of GTF. **Synopsis** ``` $ gdk test-e2e init [--gtf-version] ``` **Arguments** + `-ov`, `--gtf-version` – (Optional) The version of the GTF to use with the end-to-end testing module in the GDK project. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). This argument overrides the `gtf_version` in the GDK CLI configuration. **Output** The following example shows the output produced when you run this command to initialize the GDK project with the testing module. ``` $ gdk test-e2e init [2023-12-06 12:20:28] INFO - Using the GTF version provided in the GDK test config 1.2.0 [2023-12-06 12:20:28] INFO - Downloading the E2E testing template from GitHub into gg-e2e-tests directory... ``` ## build **Note** You must build the component by running **gdk component build** before building the end-to-end test module. Build the end-to-end testing module. The GDK CLI builds the testing module using the build system that you specify in the [GDK CLI configuration file](gdk-cli-configuration-file.md), `gdk-config.json`, under the `test-e2e` property. You must run this command in the same folder where the `gdk-config.json` file exists. By default, GDK CLI uses maven build system to build the testing module. [Maven](https://maven.apache.org/) is required to run the `gdk test-e2e build` command. You must build the component by running **gdk-component-build** before building the testing module, if the test feature files have variables like `GDK_COMPONENT_NAME` and `GDK_COMPONENT_RECIPE_FILE` to interpolate. When you run this command, the GDK CLI interpolates all of the variables from the GDK project configuration and builds the `gg-e2e-tests` module to generate the final testing JAR file. **Synopsis** ``` $ gdk test-e2e build ``` **Arguments** None **Output** The following example shows the output produced when you run this command. ``` $ gdk test-e2e build [2023-07-20 15:36:48] INFO - Updating feature file: file:///path/to//HelloWorld/greengrass-build/gg-e2e-tests/src/main/resources/greengrass/features/component.feature [2023-07-20 15:36:48] INFO - Creating the E2E testing recipe file:///path/to/HelloWorld/greengrass-build/recipes/e2e_test_recipe.yaml [2023-07-20 15:36:48] INFO - Building the E2E testing module [2023-07-20 15:36:48] INFO - Running the build command 'mvn package' ......... ``` ## run Run the testing module with the testing options in the GDK configuration file. **Note** You must build the testing module by running **gdk test-e2e build** before running the end-to-end tests. **Synopsis** ``` $ gdk test-e2e run [--gtf-options] ``` **Arguments** + `-oo`, `--gtf-options` – (Optional) Specify a list of options for running the end-to-end tests. The argument must be a valid JSON string or a file path to a JSON file containing the GTF options. The options provided in the configuration file are merged with the ones provided in the command arguments. If an option is present in both places, the one in argument takes precendence over the one from the configuration file. If the `tags` option is not specified in this command, GDK uses `Sample` for tags. If `ggc-archive` is not specified, GDK downloads the latest version of the Greengrass nucleus archive. **Output** The following example shows the output produced when you run this command. ``` $ gdk test-e2e run [2023-07-20 16:35:53] INFO - Downloading latest nucleus archive from url https://d2s8p88vqu9w66.cloudfront.net/releases/greengrass-latest.zip [2023-07-20 16:35:57] INFO - Running test jar with command java -jar /path/to/greengrass-build/gg-e2e-tests/target/uat-features-1.0.0.jar —ggc-archive=/path/to/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip —tags=Sample 16:35:59.693 [] [] [] [INFO] com.aws.greengrass.testing.modules.GreengrassContextModule - Extracting /path/to/workplace/aws-greengrass-gdk-cli/HelloWorld/greengrass-build/greengrass-nucleus-latest.zip into /var/folders/7g/ltzcb_3s77nbtmkzfb6brwv40000gr/T/gg-testing-7718418114158172636/greengrass 16:36:00.534 [gtf-1.1.0-SNAPSHOT] [] [] [INFO] com.aws.greengrass.testing.features.LoggerSteps - GTF Version is gtf-1.1.0-SNAPSHOT ....... ``` # Greengrass Development Kit CLI configuration file The AWS IoT Greengrass Development Kit Command-Line Interface (GDK CLI) reads from a configuration file named `gdk-config.json` to build and publish components. This configuration file must exist in the root of the component repository. You can use the GDK CLI [init command](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-init) to initialize component repositories with this configuration file. **Topics** + [GDK CLI configuration file format](#gdk-config-format) + [GDK CLI configuration file examples](#gdk-config-examples) ## GDK CLI configuration file format When you define a GDK CLI configuration file for a component, you specify the following information in JSON format. `gdk_version` The minimum version of the GDK CLI that is compatible with this component. This value must be one of the GDK CLI versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-gdk-cli/releases). `component` The configuration for this component. `componentName` `author` The author or publisher of the component. `version` The version of the component. Specify one of the following: + `NEXT_PATCH` – When you choose this option, the GDK CLI sets the version when you publish the component. The GDK CLI queries the AWS IoT Greengrass service to identify the latest published version of the component. Then, it sets the version to the next patch version after that version. If you haven't published the component before, the GDK CLI uses version `1.0.0`. If you choose this option, you can't use the [Greengrass CLI](greengrass-cli-component.md) to locally deploy and test the component to your local development computer that runs the AWS IoT Greengrass Core software. To enable local deployments, you must specify a semantic version instead. + A semantic version, such as **1.0.0**. Semantic versions use a *major*.*minor*.*patch* numbering system. For more information, see the [semantic version specification](https://semver.org/). If you develop components on a Greengrass core device where you want to deploy and test the component, choose this option. You must build the component with a specific version to create local deployments with the [Greengrass CLI](greengrass-cli-component.md). `build` The configuration to use to build this component's source into artifacts. This object contains the following information: `build_system` The build system to use. Choose from the following options: + `zip` – Packages the component's folder into a ZIP file to define as the component's only artifact. Choose this option for the following types of components: + Components that use interpreted programming languages, such as Python or JavaScript. + Components that package files other than code, such as machine learning models or other resources. The GDK CLI zips the component's folder into a zip file with the same name as the component folder. For example, if the component folder's name is `HelloWorld`, the GDK CLI creates a zip file named `HelloWorld.zip`. **Note** If you use GDK CLI version 1.0.0 on a Windows device, the component folder and zip file names must contain only lowercase letters. When the GDK CLI zips the component's folder into a zip file, it skips the following files: + The `gdk-config.json` file + The recipe file (`recipe.json` or `recipe.yaml`) + Build folders, such as `greengrass-build` + `maven` – Runs the `mvn clean package` command to build the component's source into artifacts. Choose this option for components that use [Maven](https://maven.apache.org/), such as Java components. On Windows devices, this feature is available for GDK CLI v1.1.0 and later. + `gradle` – Runs the `gradle build` command to build the component's source into artifacts. Choose this option for components that use [Gradle](https://gradle.org/). This feature is available for GDK CLI v1.1.0 and later. The `gradle` build system supports Kotlin DSL as the build file. This feature is available for GDK CLI v1.2.0 and later. + `gradlew` – Runs the `gradlew` command to build the component's source into artifacts. Choose this option for components that use the [Gradle Wrapper ](https://docs.gradle.org/current/userguide/gradle_wrapper.html). This feature is available for GDK CLI v1.2.0 and later. + `custom` – Runs a custom command to build the component's source into a recipe and artifacts. Specify the custom command in the `custom_build_command` parameter. `custom_build_command` (Optional) The custom build command to run for a custom build system. You must specify this parameter if you specify `custom` for `build_system`. This command must create a recipe and artifacts in the following folders within the component folder. The GDK CLI creates these folders for you when you run the [component build command](greengrass-development-kit-cli-component.md#greengrass-development-kit-cli-component-build). + Recipe folder: `greengrass-build/recipes` + Artifacts folder: `greengrass-build/artifacts/componentName/componentVersion` Replace *componentName* with the component name, and replace *componentVersion* with the component version or `NEXT_PATCH`. You can specify a single string or a list of strings, where each string is a word in the command. For example, to run a custom build command for a C\$1\$1 component, you might specify **cmake --build build --config Release** or **["cmake", "--build", "build", "--config", "Release"]**. To view an example of a custom build system, see the [aws.greengrass.labs.LocalWebServer community component on GitHub](https://github.com/awslabs/aws-greengrass-labs-local-web-server). `options` (Optional) Additional configuration options used during the component build process. This feature is available for GDK CLI v1.2.0 and later. `excludes` A list of glob patterns that define which files to exclude from the component directory when building the zip file. Only valid when the `build_system` is `zip`. In GDK CLI versions 1.4.0 and earlier, any file that matches an entry in the excludes list is excluded from all of the component's subdirectories. To achieve the same behavior in GDK CLI versions 1.5.0 and later, prepend `**/` to the existing entries in the excludes list. For example, `*.txt` will exclude text files from just the directory; `**/*.txt` will exclude text files from all directories and subdirectories. In GDK CLI versions 1.5.0 and later, you may see a warning during the component build when `excludes` is defined in the GDK configuration file. To disable this warning, set the environment variable `GDK_EXCLUDES_WARN_IGNORE` to `true`. The GDK CLI always excludes the following files from the zip file: + The `gdk-config.json` file + The recipe file (`recipe.json` or `recipe.yaml`) + Build folders, such as `greengrass-build` The following files are excluded by default. However, you can control which of these files are excluded with the `excludes` option. + Any folder that starts with the prefix "test" (`test*`) + All hidden files + The `node_modules` folder If you specify the `excludes` option, the GDK CLI excludes only those files you set with the `excludes` option. If you don't specify the `excludes` option, the GDK CLI excludes the previously noted default files and folders. `zip_name` The zip file name to use when you create a zip artifact during the build process. Only valid when the `build_system` is `zip`. If the `build_system` is empty, the component name is used for the zip file name. `publish` The configuration to use to publish this component to the AWS IoT Greengrass service. If you use GDK CLI v1.1.0 or later, you can specify the `--bucket` argument to specify the S3 bucket where the GDK CLI uploads the component's artifacts. If you don't specify this argument, the GDK CLI uploads to the S3 bucket whose name is `bucket-region-accountId`, where *bucket* and *region* are the values that you specify in `gdk-config.json`, and *accountId* is your AWS account ID. The GDK CLI creates the bucket if it doesn't exist. This object contains the following information: `bucket` The S3 bucket name to use to host component artifacts. `region` The AWS Region where the GDK CLI publishes this component. This property is optional if you are using GDK CLI v1.3.0 or later. `options` (Optional) Additional configuration options used during component version creation. This feature is available for GDK CLI v1.2.0 and later. `file_upload_args` A JSON structure containing arguments sent to Amazon S3 while uploading files to a bucket, such as metadata and encryption mechanisms. For a list of the allowed arguments, see the [https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/customizations/s3.html#boto3.s3.transfer.S3Transfer.ALLOWED_UPLOAD_ARGS) class in the *Boto3 documentation.*. `test-e2e` (Optional) The configuration to use during end-to-end testing of the component. This feature is available for GDK CLI v1.3.0 and later. `build` `build_system` – The build system to use. Default option is `maven`. Choose from the following options: + `maven` – Runs the `mvn package` command to build the testing module. Choose this option for building the testing module that uses [Maven](https://maven.apache.org/). + `gradle` – Runs the `gradle build` command to build the testing module. Choose this option for the testing module that uses [Gradle](https://gradle.org/). `gtf_version` (Optional) The version of the Greengrass Testing Framework (GTF) to use as a dependency of the end-to-end testing module when you initialize the GDK project with GTF. This value must be one of the GTF versions from [ releases](https://github.com/aws-greengrass/aws-greengrass-testing/releases). The default is GTF version 1.1.0. `gtf_options` (Optional) Additional configuration options used during the end-to-end testing of the component. The following list includes the options you can use with GTF version 1.1.0. + `additional-plugins` – (Optional) Additional Cucumber plugins + `aws-region` – Targets specific regional endpoints for AWS services. Defaults to what the AWS SDK discovers. + `credentials-path` – Optional AWS profile credentials path. Defaults to credentials discovered on host environment. + `credentials-path-rotation` – Optional rotation duration for AWS credentials. Defaults to 15 minutes or `PT15M`. + `csr-path` – The path for the CSR using which the device certificate will be generated. + `device-mode` – The target device under test. Defaults to local device. + `env-stage` – Targets the deployment environment of Greengrass. Defaults to production. + `existing-device-cert-arn` – The arn of an existing certificate that you want to use as a device certificate for Greengrass. + `feature-path` – File or directory containing additional feature files. Default is no additional feature files are used. + `gg-cli-version` – Overrides the version of the Greengrass CLI. Defaults to the value found in `ggc.version`. + `gg-component-bucket` – The name of an existing Amazon S3 bucket that houses Greengrass components. + `gg-component-overrides` – A list of Greengrass component overrides. + `gg-persist` – A list of test elements to persist after a test run. Default behavior is to persist nothing. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`. + `gg-runtime` – A list of values to influence how the test interacts with testing resources. These values supersede the `gg.persist` parameter. If the default is empty, it assumes all testing resources are manged by test case, including the installed Greengrass runtime. Accepted values are: `aws.resources`, `installed.software`, and `generated.files`. + `ggc-archive` – The path to the archived Greengrass nucleus component. + `ggc-install-root` – Directory to install the Greengrass nucleus component. Defaults to test.temp.path and test run folder. + `ggc-log-level` – Set the Greengrass nucleus log level for the test run. Default is "INFO". + `ggc-tes-rolename` – The IAM role that AWS IoT Greengrass Core will assume to access AWS services. If a role with given name does not exist then one will be created and default access policy. + `ggc-trusted-plugins` – The comma separate list of the paths (on host) of the trusted plugins that need to added to Greengrass. To provide the path on the DUT itself, prefix the path with 'dut:' + `ggc-user-name` – The user:group posixUser value for the Greengrass nucleus. Defaults to the current username that is logged in. + `ggc-version` – Overrides the version of the running Greengrass nucleus component. Defaults to the value found in ggc.archive. + `log-level` – Log level of the test run. Defaults to "INFO". + `parallel-config` – Set of batch index and number of batches as a JSON String. Default value of batch index is 0 and number of batches is 1. + `proxy-url` – Configure all tests to route traffic through this URL. + `tags` – Only run feature tags. Can be intersected with '&' + `test-id-prefix` – A common prefix applied to all test specific resources including AWS resource names and tags. Default is a "gg" prefix. + `test-log-path` – Directory that will contain the results of the entire test run. Defaults to "testResults". + `test-results-json` – Flag to determine if a resulting Cucumber JSON report is generated written to disk. Defaults to true. + `test-results-log` – Flag to determine if the console output is generated written to disk. Defaults to false. + `test-results-xml` – Flag to determine if a resulting JUnit XML report is generated written to disk. Defaults to true. + `test-temp-path` – Directory to generate local test artifacts. Defaults to a random temp directory prefixed with gg-testing. + `timeout-multiplier` – Multiplier provided to all test timeouts. Default is 1.0. ## GDK CLI configuration file examples You can reference the following GDK CLI configuration file examples to help you configure Greengrass component environments. ### Hello World (Python) The following GDK CLI configuration file supports a Hello World component that runs a Python script. This configuration file uses the `zip` build system to package the component's Python script into a ZIP file that the GDK CLI uploads as an artifact. ``` { "component": { "com.example.PythonHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "zip", "options": { "excludes": [".*"] } }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2", "options": { "file_upload_args": { "Metadata": { "some-key": "some-value" } } } } }, "test-e2e":{ "build":{ "build_system": "maven" }, "gtf_version": "1.1.0", "gtf_options": { "tags": "Sample" } }, "gdk_version": "1.6.1" } } ``` ### Hello World (Java) The following GDK CLI configuration file supports a Hello World component that runs a Java application. This configuration file uses the `maven` build system to package the component's Java source code into a JAR file that the GDK CLI uploads as an artifact. ``` { "component": { "com.example.JavaHelloWorld": { "author": "Amazon", "version": "NEXT_PATCH", "build": { "build_system" : "maven" }, "publish": { "bucket": "greengrass-component-artifacts", "region": "us-west-2", "options": { "file_upload_args": { "Metadata": { "some-key": "some-value" } } } } }, "test-e2e":{ "build":{ "build_system": "maven" }, "gtf_version": "1.1.0", "gtf_options": { "tags": "Sample" } }, "gdk_version": "1.6.1" } } ``` ### Community components Several community components in the [Greengrass Software Catalog](greengrass-software-catalog.md) use the GDK CLI. You can explore the GDK CLI configuration files in these components' repositories. **To view community components' GDK CLI configuration files** 1. Run the following command to list the community components that use the GDK CLI. ``` gdk component list --repository ``` The response lists the name of the GitHub repository for each community component that uses the GDK CLI. Each repository exists in the `awslabs` organization. ``` [2022-02-22 17:27:31] INFO - Listing all the available component repositories from Greengrass Software Catalog. [2022-02-22 17:27:31] INFO - Found '6' component repositories to display. 1. aws-greengrass-labs-database-influxdb 2. aws-greengrass-labs-telemetry-influxdbpublisher 3. aws-greengrass-labs-dashboard-grafana 4. aws-greengrass-labs-dashboard-influxdb-grafana 5. aws-greengrass-labs-local-web-server 6. aws-greengrass-labs-lookoutvision-gstreamer ``` 1. Open a community component's GitHub repository at the following URL. Replace *community-component-name* with the name of a community component from the previous step. ``` https://github.com/awslabs/community-component-name ```