# 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 ```