# Greengrass Command Line Interface The Greengrass Command Line Interface (CLI) lets you interact with AWS IoT Greengrass Core on your device to locally develop components and debug issues. For example, you can use the Greengrass CLI to create a local deployment and restart a component on the core device. Deploy the [Greengrass CLI component](greengrass-cli-component.md) (`aws.greengrass.Cli`) to install the Greengrass CLI on your core device. **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. **Topics** + [Install the Greengrass CLI](install-gg-cli.md) + [Greengrass CLI commands](gg-cli-reference.md) # 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 AWS 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 AWS IoT Greengrass V2](getting-started.md). ## Prerequisites To deploy the Greengrass CLI component, you must meet the following requirements: + AWS IoT Greengrass Core software installed and configured on your core device. For more information, see [Tutorial: Getting started with AWS IoT Greengrass V2](getting-started.md). + To use the AWS CLI to deploy the Greengrass CLI, you must have installed and configured the AWS CLI. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) in the *AWS Command Line Interface User Guide*. + 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](greengrass-cli-component.md#greengrass-cli-component-configuration). ## Deploy the Greengrass CLI component Complete the following steps to deploy the Greengrass CLI component to your core device: ### To deploy the Greengrass CLI component (console) 1. Sign in to the [AWS IoT Greengrass console](https://console.aws.amazon.com/greengrass). 1. In the navigation menu, choose **Components**. 1. On the **Components** page, on the **Public components** tab, choose `aws.greengrass.Cli`. 1. On the **aws.greengrass.Cli** page, choose **Deploy**. 1. From **Add to deployment**, choose **Create new deployment**. 1. 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**. 1. On the **Select components** page, verify that the **aws.greengrass.Cli** component is selected, and choose **Next**. 1. On the **Configure components** page, keep the default configuration settings, and choose **Next**. 1. On the **Configure advanced setting** page, keep the default configuration settings, and choose **Next**. 1. On the **Review** page, click **Deploy** ### To deploy the Greengrass CLI component (AWS CLI) 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.17.0", "configurationUpdate": { "merge": "{\"AuthorizedPosixGroups\":\",,...,\",\"AuthorizedWindowsGroups\":\",,...,\"}" } } } } ``` + 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:iot:region:account-id:thing/thingName` + Thing group: `arn:aws: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 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. `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 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. 1. 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=] [COMMAND] Greengrass command line interface --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 AWS IoT Greengrass V2](troubleshooting.md). # Greengrass CLI commands The Greengrass CLI provides a command line interface to interact locally with your AWS IoT Greengrass core device. Greengrass CLI commands use the following format. ``` $ greengrass-cli [arguments] ``` By default, the `greengrass-cli` executable file in the `/greengrass/v2/bin/` folder interacts with the version of the AWS IoT Greengrass Core software running in the `/greengrass/v2` folder. If you call an executable that is not placed in this location, or if you want to interact with AWS IoT Greengrass Core software in a different location, then you must use one of the following methods to explicitly specify the root path of the AWS IoT Greengrass Core software that you want to interact with: + Set the `GGC_ROOT_PATH` environment variable to `/greengrass/v2`. + Add the `--ggcRootPath /greengrass/v2` argument to your command as shown in the following example. ``` greengrass-cli --ggcRootPath /greengrass/v2 [arguments] ``` You can use the following arguments with any command: + Use `--help` for information about a specific Greengrass CLI command. + Use `--version` for information about the Greengrass CLI version. This section describes the Greengrass CLI commands and provides examples for these commands. The synopsis for each command shows its arguments and their usage. Optional arguments are shown in square brackets. **Topics** + [component](gg-cli-component.md) + [deployment](gg-cli-deployment.md) + [logs](gg-cli-logs.md) + [get-debug-password](gg-cli-get-debug-password.md) # component Use the `component` command to interact with local components on your core device. **Subcommands** + [details](#component-details) + [list](#component-list) + [restart](#component-restart) + [stop](#component-stop) ## details Retrieve the version, status, and configuration of one component. **Synopsis** ``` greengrass-cli component details --name ``` **Arguments** `--name`, `-n`. The component name. **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli component details --name MyComponent Component Name: MyComponent Version: 1.0.0 State: RUNNING Configuration: null ``` ## list Retrieve the name, version, status, and configuration of each component installed on the device. **Synopsis** ``` greengrass-cli component list ``` **Arguments** None **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli component list Components currently running in Greengrass: Component Name: FleetStatusService Version: 0.0.0 State: RUNNING Configuration: {"periodicUpdateIntervalSec":86400.0} Component Name: UpdateSystemPolicyService Version: 0.0.0 State: RUNNING Configuration: null Component Name: aws.greengrass.Nucleus Version: 2.0.0 State: FINISHED Configuration: {"awsRegion":"region","runWithDefault":{"posixUser":"ggc_user:ggc_group"},"telemetry":{}} Component Name: DeploymentService Version: 0.0.0 State: RUNNING Configuration: null Component Name: TelemetryAgent Version: 0.0.0 State: RUNNING Configuration: null Component Name: aws.greengrass.Cli Version: 2.0.0 State: RUNNING Configuration: {"AuthorizedPosixGroups":"ggc_user"} ``` ## restart Restart components. **Synopsis** ``` greengrass-cli component restart --names ,... ``` **Arguments** `--names`, `-n`. The component name. At least one component name is required. You can specify additional component names, separating each name with a comma. **Output** None ## stop Stop running components. **Synopsis** ``` greengrass-cli component stop --names ,... ``` **Arguments** `--names`, `-n`. The component name. At least one component name is required. You can specify additional component names if needed, separating each name with a comma. **Output** None # deployment Use the `deployment` command to interact with local components on your core device. To monitor the progress of a local deployment, use the `status` subcommand. You can't monitor the progress of a local deployment using the console. **Subcommands** + [create](#deployment-create) + [cancel](#deployment-cancel) + [list](#deployment-list) + [status](#deployment-status) ## create Create or update a local deployment using specified component recipes, artifacts, and runtime arguments. **Synopsis** ``` greengrass-cli deployment create --recipeDir path/to/component/recipe [--artifactDir path/to/artifact/folder ] [--update-config {component-configuration}] [--groupId ] [--merge "="]... [--runWith ":posixUser=[:]"]... [--systemLimits "{component-system-resource-limits}]"]... [--remove ,...] [--failure-handling-policy ] ``` **Arguments** + `--recipeDir`, `-r`. The full path to the folder that contains the component recipe files. + `--artifactDir`, `-a`. The full path to the folder that contains the artifact files you want to include in your deployment. The artifacts folder must contain the following directory structure: ``` /path/to/artifact/folder/// ``` + `--update-config`, `-c`. The configuration arguments for the deployment, provided as a JSON string or a JSON file. The JSON string should be in the following format: ``` { \ "componentName": { \ "MERGE": {"config-key": "config-value"}, \ "RESET": ["path/to/reset/"] \ } \ } ``` `MERGE` and `RESET` are case-sensitive and must be in upper case. + `--groupId`, `-g`. The target thing group for the deployment. + `--merge`, `-m`. The name and version of the target component that you want to add or update. You must provide the component information in the format `=`. Use a separate argument for each additional component to specify. If needed, use the `--runWith` argument to provide the `posixUser`, `posixGroup`, and `windowsUser` information for running the component. + `--runWith`. The `posixUser`, `posixGroup`, and `windowsUser` information for running a generic or Lambda component. You must provide this information in the format `:{posixUser|windowsUser}=[:<=posixGroup>]`. For example, you might specify **HelloWorld:posixUser=ggc\$1user:ggc\$1group** or **HelloWorld:windowsUser=ggc\$1user**. Use a separate argument for each additional option to specify. For more information, see [Configure the user that runs components](configure-greengrass-core-v2.md#configure-component-user). + `--systemLimits`. The system resource limits to apply to generic and non-containerized Lambda components' processes on the core device. You can configure the maximum amount of CPU and RAM usage that each component's processes can use. Specify a serialized JSON object or a file path to a JSON file. The JSON object must have the following format. ``` { \ "componentName": { \ "cpus": cpuTimeLimit, \ "memory": memoryLimitInKb \ } \ } ``` You can configure the following system resource limits for each component: + `cpus` – The maximum amount of CPU time that this component's processes can use on the core device. A core device's total CPU time is equivalent to the device's number of CPU cores. For example, on a core device with 4 CPU cores, you can set this value to `2` to limit this component's processes to 50 percent usage of each CPU core. On a device with 1 CPU core, you can set this value to `0.25` to limit this component's processes to 25 percent usage of the CPU. If you set this value to a number greater than the number of CPU cores, the AWS IoT Greengrass Core software doesn't limit the component's CPU usage. + `memory` – The maximum amount of RAM (in kilobytes) that this component's processes can use on the core device. For more information, see [Configure system resource limits for components](configure-greengrass-core-v2.md#configure-component-system-resource-limits). This feature is available for v2.4.0 and later of the [Greengrass nucleus component](greengrass-nucleus-component.md) and Greengrass CLI on Linux core devices. AWS IoT Greengrass doesn't currently support this feature on Windows core devices. + `--remove`. The name of the target component that you want to remove from a local deployment. If the component defines an [uninstall lifecycle](component-recipe-reference.md#uninstall-lifecycle-definition) step, the AWS IoT Greengrass Core software runs the uninstall script before removing the component. To remove a component that was merged from a cloud deployment, you must provide the group ID of the target thing group in the following format: ------ #### [ Greengrass nucleus v2.4.0 and later ] ``` --remove --groupId ``` ------ #### [ Earlier than v2.4.0 ] ``` --remove --groupId thinggroup/ ``` ------ + `--failure-handling-policy`. Defines the action taken when a deployment fails. There are two actions that you can specify: + `ROLLBACK` – + `DO_NOTHING` – This feature is available for v2.11.0 and later of the [Greengrass nucleus](greengrass-nucleus-component.md). **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli deployment create \ --merge MyApp1=1.0.0 \ --merge MyApp2=1.0.0 --runWith MyApp2:posixUser=ggc_user \ --remove MyApp3 \ --recipeDir recipes/ \ --artifactDir artifacts/ Local deployment has been submitted! Deployment Id: 44d89f46-1a29-4044-ad89-5151213dfcbc ``` ## cancel Cancels the specified deployment. Synopsis ``` greengrass-cli deployment cancel -i ``` Arguments `-i`. The unique identifier of the deployment to cancel. The deployment ID is returned in the output of the `create` command. Output + None ## list Retrieve the status of the last 10 local deployments. **Synopsis** ``` greengrass-cli deployment list ``` **Arguments** None **Output** The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`. ``` $ sudo greengrass-cli deployment list 44d89f46-1a29-4044-ad89-5151213dfcbc: SUCCEEDED Created on: 6/27/23 11:05 AM ``` ## status Retrieve the status of a specific deployment. **Synopsis** ``` greengrass-cli deployment status -i ``` **Arguments** `-i`. The ID of the deployment. **Output** The following example shows the output produced when you run this command. Depending on the status of your deployment, the output shows one of the following status values: `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`. ``` $ sudo greengrass-cli deployment status -i 44d89f46-1a29-4044-ad89-5151213dfcbc 44d89f46-1a29-4044-ad89-5151213dfcbc: FAILED Created on: 6/27/23 11:05 AM Detailed Status: Deployment Error Stack: List of error codes Deployment Error Types: List of error types Failure Cause: Cause ``` # logs Use the `logs` command to analyze Greengrass logs on your core device. **Subcommands** + [get](#logs-get) + [list-keywords](#logs-list-keywords) + [list-log-files](#logs-list-log-files) ## get Collect, filter, and visualize Greengrass log files. This command supports only JSON-formatted log files. You can specify the [logging format](greengrass-nucleus-component.md#greengrass-nucleus-component-configuration-logging-format) in the nucleus configuration. **Synopsis** ``` greengrass-cli logs get [--log-dir path/to/a/log/folder] [--log-file path/to/a/log/file] [--follow true | false ] [--filter ] [--time-window , ] [--verbose ] [--no-color ] [--before ] [--after ] [--syslog ] [--max-long-queue-size ] ``` **Arguments** + `--log-dir`, `-ld`. The path to the directory to check for log files, such as **`/greengrass/v2`/logs**. Do not use with `--syslog`. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command. + `--log-file`, `-lf`. The paths to the log directories you want to use. Use a separate argument for each additional directory to specify. You must use at least one of `--log-dir` or `--log-file`. You can also use both arguments in a single command. + `--follow`, `-fol`. Show log updates as they occur. Greengrass CLI continues to run and reads from the specified logs. If you specify a time window, then Greengrass CLI stops monitoring logs after all of the time windows end. + `--filter`, `-f`. The keyword, regular expressions, or key-value pair to use as a filter. Provide this value as a string, a regular expression, or as a key-value pair. Use a separate argument for each additional filter to specify. When evaluated, multiple filters specified in a single argument are separated by OR operators, and filters specified in additional arguments are combined with AND operators. For example, if your command includes `--filter "installed" --filter "name=alpha,name=beta"`, then Greengrass CLI will filter and display log messages that contain both the keyword `installed` and a `name` key that has the values `alpha` or `beta`. + `--time-window`, `-t`. The time window for which to show log information. You can use both exact timestamps and relative offsets. You must provide this information in the format `,`. If you do not specify either the begin time or the end time, then the value for that option defaults to the current system date and time. Use a separate argument for each additional time window to specify. Greengrass CLI supports the following formats for timestamps: + `yyyy-MM-DD`, for example, `2020-06-30`. The time defaults to 00:00:00 when you use this format. `yyyyMMDD`, for example, `20200630`. The time defaults to 00:00:00 when you use this format. `HH:mm:ss`, for example, `15:30:45`. The date defaults to the current system date when you use this format. `HH:mm:ssSSS`, for example, `15:30:45`. The date defaults the current system date when you use this format. `YYYY-MM-DD'T'HH:mm:ss'Z'`, for example, `2020-06-30T15:30:45Z`. `YYYY-MM-DD'T'HH:mm:ss`, for example, `2020-06-30T15:30:45`. `yyyy-MM-dd'T'HH:mm:ss.SSS`, for example, `2020-06-30T15:30:45.250`. Relative offsets specify a time period offset from the current system time. Greengrass CLI supports the following format for relative offsets: `+|-[h|hr|hours][valuem|min|minutes][value]s|sec|seconds`. For example, the following argument to specify a time window between 1 hour and 2 hours 15 minutes before the current time is `--time-window -2h15min,-1hr`. + `--verbose`. Show all fields from the log messages. Do not use with `--syslog`. + `--no-color`, `-nc`. Remove color coding. The default color coding for log messages uses bold red text. Supports only UNIX-like terminals because it uses ANSI escape sequences. + `--before`, `-b`. The number of lines to show preceding a matched log entry. Default is 0. + `--after`, `-a`. The number of lines to show following a matched log entry. Default is 0. + `--syslog`. Process all log files using the syslog protocol defined by RFC3164. Do not use with `--log-dir` and `--verbose`. The syslog protocol uses the following format: `"<$Priority>$Timestamp $Host $Logger ($Class): $Message"`. If you do not specify a log file, then Greengrass CLI reads log messages from the following locations: `/var/log/messages`, `/var/log/syslog`, or the `/var/log/system.log`. AWS IoT Greengrass doesn't currently support this feature on Windows core devices. + `--max-log-queue-size`, `-m`. The maximum number of log entries to allocate to memory. Use this option to optimize memory usage. Default is 100. **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli logs get --verbose \ --log-file /greengrass/v2/logs/greengrass.log \ --filter deployment,serviceName=DeploymentService \ --filter level=INFO \ --time-window 2020-12-08T01:11:17,2020-12-08T01:11:22 2020-12-08T01:11:17.615Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.DeploymentService: Current deployment finished. {DeploymentId=44d89f46-1a29-4044-ad89-5151213dfcbc, serviceName=DeploymentService, currentState=RUNNING} 2020-12-08T01:11:17.675Z [INFO] (pool-2-thread-14) com.aws.greengrass.deployment.IotJobsHelper: Updating status of persisted deployment. {Status=SUCCEEDED, StatusDetails={detailed-deployment-status=SUCCESSFUL}, ThingName=MyThing, JobId=22d89f46-1a29-4044-ad89-5151213dfcbc ``` ## list-keywords Show suggested keywords that you can use to filter log files. **Synopsis** ``` greengrass-cli logs list-keywords [arguments] ``` **Arguments** None **Output** The following examples show the output produced when you run this command. ``` $ sudo greengrass-cli logs list-keywords Here is a list of suggested keywords for Greengrass log: level=$str thread=$str loggerName=$str eventType=$str serviceName=$str error=$str ``` ``` $ sudo greengrass-cli logs list-keywords --syslog Here is a list of suggested keywords for syslog: priority=$int host=$str logger=$str class=$str ``` ## list-log-files Show log files located in a specified directory. **Synopsis** ``` greengrass-cli logs list-log-files [arguments] ``` **Arguments** `--log-dir`, `-ld`. The path to the directory to check for log files. **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli logs list-log-files -ld /greengrass/v2/logs/ /greengrass/v2/logs/aws.greengrass.Nucleus.log /greengrass/v2/logs/main.log /greengrass/v2/logs/greengrass.log Total 3 files found. ``` # get-debug-password Use the `get-debug-password` command to print a randomly generated password for the [local debug console component](local-debug-console-component.md) (`aws.greengrass.LocalDebugConsole`). The password expires 8 hours after it is generated. **Synopsis** ``` greengrass-cli get-debug-password ``` **Arguments** None **Output** The following example shows the output produced when you run this command. ``` $ sudo greengrass-cli get-debug-password Username: debug Password: bEDp3MOHdj8ou2w5de_sCBI2XAaguy3a8XxREXAMPLE Password expires at: 2021-04-01T17:01:43.921999931-07:00 The local debug console is configured to use TLS security. The certificate is self-signed so you will need to bypass your web browser's security warnings to open the console. Before you bypass the security warning, verify that the certificate fingerprint matches the following fingerprints. SHA-256: 15 0B 2C E2 54 8B 22 DE 08 46 54 8A B1 2B 25 DE FB 02 7D 01 4E 4A 56 67 96 DA A6 CC B1 D2 C4 1B SHA-1: BC 3E 16 04 D3 80 70 DA E0 47 25 F9 90 FA D6 02 80 3E B5 C1 ```