Greengrass CLI - AWS IoT Greengrass

Greengrass CLI

The Greengrass CLI component (aws.greengrass.Cli) provides a local command-line interface that you can use on core devices to develop and debug components locally. The Greengrass CLI lets you create local deployments and restart components on the core device, for example.

You can install this component when you install the AWS IoT Greengrass Core software. For more information, see Getting started with AWS IoT Greengrass V2.

Important

We recommend that you use this component in only development environments, not production environments. This component provides access to information and operations that you typically won't need in a production environment. Follow the principle of least privilege by deploying this component to only core devices where you need it.

After you install this component, run the following command to view its help documentation. When this component installs, it adds a symbolic link to greengrass-cli in the /greengrass/v2/bin folder. You can run the Greengrass CLI from this path or add it to your PATH environment variable to run greengrass-cli without its absolute path.

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

The following command restarts a component named com.example.HelloWorld, for example.

Linux or Unix
sudo /greengrass/v2/bin/greengrass-cli component restart --names "com.example.HelloWorld"
Windows
C:\greengrass\v2\bin\greengrass-cli component restart --names "com.example.HelloWorld"

For more information, see Greengrass Command Line Interface.

Versions

This component has the following versions:

  • 2.5.x

  • 2.4.x

  • 2.3.x

  • 2.2.x

  • 2.1.x

  • 2.0.x

Type

This component is a plugin component (aws.greengrass.plugin). The Greengrass nucleus runs this component in the same Java Virtual Machine (JVM) as the nucleus. The nucleus restarts when you change this component's version on the core device.

This component uses the same log file as the Greengrass nucleus. For more information, see Monitor AWS IoT Greengrass logs.

For more information, see Component types.

Operating system

This component can be installed on core devices that run the following operating systems:

  • Linux

  • Windows

Requirements

This component has the following requirements:

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

    • Use the system user that runs the AWS 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.

Dependencies

When you deploy a component, AWS IoT Greengrass also deploys compatible versions of its dependencies. This means that you must meet the requirements for the component and all of its dependencies to successfully deploy the component. This section lists the dependencies for the released versions of this component and the semantic version constraints that define the component versions for each dependency. You can also view the dependencies for each version of the component in the AWS IoT Greengrass console. On the component details page, look for the Dependencies list.

2.5.0 - 2.5.2

The following table lists the dependencies for versions 2.5.0 through 2.5.2 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.5.0 <2.6.0 Soft
2.4.0

The following table lists the dependencies for version 2.4.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.5.0 Soft
2.3.0

The following table lists the dependencies for version 2.3.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.4.0 Soft
2.2.0

The following table lists the dependencies for version 2.2.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.3.0 Soft
2.1.0

The following table lists the dependencies for version 2.1.0 of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.1.0 <2.2.0 Soft
2.0.x

The following table lists the dependencies for version 2.0.x of this component.

Dependency Compatible versions Dependency type
Greengrass nucleus >=2.0.0 <2.1.0 Soft
Note

The minimum compatible version of the Greengrass nucleus corresponds to the patch version of the Greengrass CLI component.

For more information about component dependencies, see the component recipe reference.

Configuration

This component provides the following configuration parameters that you can customize when you deploy the component.

2.5.x
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 AWS 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 AWS IoT Greengrass Core software.

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 AWS 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 AWS IoT Greengrass Core software.

Example: Configuration merge update

The following example configuration specifies to authorize three POSIX system groups (group1, 1002, and group3) and two Windows user groups (Device Operators and QA Engineers) to use the Greengrass CLI.

{ "AuthorizedPosixGroups": "group1,1002,group3", "AuthorizedWindowsGroups": "Device Operators,QA Engineers" }
2.4.x - 2.0.x
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 AWS 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 AWS IoT Greengrass Core software.

Example: Configuration merge update

The following example configuration specifies to authorize three system groups (group1, 1002, and group3) to use the Greengrass CLI.

{ "AuthorizedPosixGroups": "group1,1002,group3" }

Local log file

This component uses the same log file as the Greengrass nucleus component.

Linux
/greengrass/v2/logs/greengrass.log
Windows
C:\greengrass\v2\logs\greengrass.log

To view this component's logs

  • Run the following command on the core device to view this component's log file in real time. Replace /greengrass/v2 or C:\greengrass\v2 with the path to the AWS IoT Greengrass root folder.

    Linux
    sudo tail -f /greengrass/v2/logs/greengrass.log
    Windows (PowerShell)
    Get-Content C:\greengrass\v2\logs\greengrass.log -Tail 10 -Wait

Changelog

The following table describes the changes in each version of the component.

Version

Changes

2.5.2

Version updated for Greengrass nucleus version 2.5.2 release.

2.5.1

Version updated for Greengrass nucleus version 2.5.1 release.

2.5.0

New features
  • Adds support for core devices that run Windows.

  • Adds the new AuthorizedWindowsGroups configuration parameter that you can specify to authorize system groups to use the Greengrass CLI on Windows devices.

  • Adds the windowsUser parameter for local deployments. You can use this parameter specify the user to use to run components on a Windows core device.

2.4.0

New features

2.3.0

Version updated for Greengrass nucleus version 2.3.0 release.

2.2.0

Version updated for Greengrass nucleus version 2.2.0 release.

2.1.0

Version updated for Greengrass nucleus version 2.1.0 release.

2.0.5

Version updated for Greengrass nucleus version 2.0.5 release.

2.0.4

Version updated for Greengrass nucleus version 2.0.4 release.

2.0.3

Initial version.