Install the Greengrass CLI - Amazon IoT Greengrass
PrerequisitesDeploy the Greengrass CLI component
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Install the Greengrass CLI

You can install the Greengrass CLI in one of the following ways:

  • Use the --deploy-dev-tools argument when you first set up Amazon IoT Greengrass Core software on your device. You must also specify --provision true to apply this argument.

  • Deploy the Greengrass CLI component (aws.greengrass.Cli) on your device.

This section describes the steps to deploy the Greengrass CLI component. For information about installing the Greengrass CLI during initial setup, see Tutorial: Getting started with Amazon IoT Greengrass V2.

Prerequisites

To deploy the Greengrass CLI component, you must meet the following requirements:

  • Amazon IoT Greengrass Core software installed and configured on your core device. For more information, see Tutorial: Getting started with Amazon IoT Greengrass V2.

  • To use the Amazon CLI to deploy the Greengrass CLI, you must have installed and configured the Amazon CLI. For more information, see Configuring the Amazon CLI in the Amazon Command Line Interface User Guide.

  • You must be authorized to use the Greengrass CLI to interact with the Amazon IoT Greengrass Core software. Do one of the following to use the Greengrass CLI:

    • Use the system user that runs the Amazon IoT Greengrass Core software.

    • Use a user with root or adminstrative permissions. On Linux core devices, you can use sudo to gain root permissions.

    • Use a system user that's in a group that you specify in the AuthorizedPosixGroups or AuthorizedWindowsGroups configuration parameters when you deploy the component. For more information, see Greengrass CLI component configuration.

Deploy the Greengrass CLI component

Complete the following steps to deploy the Greengrass CLI component to your core device:

  1. Sign in to the Amazon IoT Greengrass console.

  2. In the navigation menu, choose Components.

  3. On the Components page, on the Public components tab, choose aws.greengrass.Cli.

  4. On the aws.greengrass.Cli page, choose Deploy.

  5. From Add to deployment, choose Create new deployment.

  6. On the Specify target page, under Deployment targets, in the Target name list, choose the Greengrass group that you want to deploy to, and choose Next.

  7. On the Select components page, verify that the aws.greengrass.Cli component is selected, and choose Next.

  8. On the Configure components page, keep the default configuration settings, and choose Next.

  9. On the Configure advanced setting page, keep the default configuration settings, and choose Next.

  10. On the Review page, click Deploy

  1. On your device, create a deployment.json file to define the deployment configuration for the Greengrass CLI component. This file should look like the following:

    {
  "targetArn":"targetArn",
  "components": {
    "aws.greengrass.Cli": {
      "componentVersion": "2.12.3",
      "configurationUpdate": {
        "merge": "{\"AuthorizedPosixGroups\":\"<group1>,<group2>,...,<groupN>\",\"AuthorizedWindowsGroups\":\"<group1>,<group2>,...,<groupN>\"}"
      }
    }
  }
}

    • In the target field, replace targetArn with the Amazon Resource Name (ARN) of the thing or thing group to target for the deployment, in the following format:

      • Thing: arn:aws-cn:iot:region:account-id:thing/thingName

      • Thing group: arn:aws-cn:iot:region:account-id:thinggroup/thingGroupName

    • In the aws.greengrass.Cli component object, specify values as follows:

      version

      The version of the Greengrass CLI component.

      configurationUpdate.AuthorizedPosixGroups

      (Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the Amazon IoT Greengrass Core software. You can specify group names or group IDs. For example, group1,1002,group3 authorizes three system groups (group1, 1002, and group3) to use the Greengrass CLI.

      If you don't specify any groups to authorize, you can use the Greengrass CLI as the root user (sudo) or as the system user that runs the Amazon IoT Greengrass Core software.

      configurationUpdate.AuthorizedWindowsGroups

      (Optional) A string that contains a comma-separated list of system groups. You authorize these system groups to use the Greengrass CLI to interact with the Amazon IoT Greengrass Core software. You can specify group names or group IDs. For example, group1,1002,group3 authorizes three system groups (group1, 1002, and group3) to use the Greengrass CLI.

      If you don't specify any groups to authorize, you can use the Greengrass CLI as an administrator or as the system user that runs the Amazon IoT Greengrass Core software.

  2. Run the following command to deploy the Greengrass CLI component on the device:

    $ aws greengrassv2 create-deployment --cli-input-json file://path/to/deployment.json

During installation, the component adds a symbolic link to greengrass-cli in the /greengrass/v2/bin folder on your device, and you run the Greengrass CLI from this path. To run the Greengrass CLI without its absolute path, add your /greengrass/v2/bin folder to your PATH variable. To verify the Greengrass CLI installation, run the following command:

Linux or Unix
/greengrass/v2/bin/greengrass-cli help
Windows
C:\greengrass\v2\bin\greengrass-cli help

You should see the following output:

Usage: greengrass-cli [-hV] [--ggcRootPath=<ggcRootPath>] [COMMAND]
Greengrass command line interface

      --ggcRootPath=<ggcRootPath>
                  The AWS IoT Greengrass V2 root directory.
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.
Commands:
  help                Show help information for a command.
  component           Retrieve component information and stop or restart
                        components.
  deployment          Create local deployments and retrieve deployment status.
  logs                Analyze Greengrass logs.
  get-debug-password  Generate a password for use with the HTTP debug view
                        component.

If the greengrass-cli isn't found, the deployment might have failed to install the Greengrass CLI. For more information, see Troubleshooting Amazon IoT Greengrass V2.