As of edgeCore v3.8.5, the distribution includes a command line interface, which will ultimately replace some of the functionality of the edge.bat/edge.sh script file. The commands to be replaced will have a deprecation warning until edgeCore v4.0, at which point they will be completely replaced. To access the new Edge CLI features (prior to version 4.0), use es-cli.sh.

Running Edge CLI #

With the exception of the help command, the edgeCore server must be running for the new Edge CLI commands to work. All Edge CLI commands must be in the following format:

MacOS and Linux
bin/es-cli.sh --user username [--pass password] command [arguments]

When passing credentials as arguments, their location in the list of arguments is not important (e.g. command [arguments] can come before the credentials). Order is only important for the command and command arguments themselves, as the command must come before the arguments for Edge CLI to properly consume them.

On Windows, es-cli.bat does not yet (v3.8.5+) exist to wrap CLI commands. As such, the .jar file must be called directly. If necessary, manually create the cli.properties file, and run the following command:

Windows (3.8.5+)
java -Dedge.cli.config=path/to/cli.properties -jar bin/cli/edge-cli-3.8.5.jar --user username [--pass password] command [arguments]
 
Example: C:\opt\edgeCore -3.8.5-GA\bin>java -Dedge.cli.config="C:\opt\edgeCore-3.8.5-GA\bin\cli\cli.properties" -jar "C:\opt\edgeCore-3.8.5-GA\bin\cli\edge-cli-3.8.5.jar" --user admin --pass admin sysinfo

As of edgeSuite v3.11.1, es-cli.bat now exists and the following command can be used:

Windows (3.11.1+)
bin\es-cli.bat --user username [--pass password] command [arguments]
Example: C:\opt\edgeCore-3.11.1-GA\bin>es-cli.bat --user admin --pass admin sysinfo

If [–pass password] is not provided, the application will provide a masked password prompt for entry.

Pre-authenticated Access #

If accessing the CLI from the same host running edgeCoreand the edgeCoreinstance has designated a user for CLI access (see Configuration Settings below), the username and password arguments can be omitted:

bin/es-cli.sh command [arguments]

Supported Commands #

Command / Alias
Args
Description
Role Required
action -n NAME

[-v VARS…]

Invoke a server action, passing in optional node variables.

-n NAME: Required. The name of an existing server action in the edgeCore pipeline.

-v VARS: Optional. If set, provide one or more “varName=varValue” entries to set the node variables for the action invocatione.g. -v “foo=bar” “code=1337”

none
backup, bak

[–listpages]

[-f FILENAME]

[-p PAGES]

[-l]

[-c]

Creates a backup with the given filename (full backup by default). Will overwrite backups of the same name. 

Running –listpages will return a list of all archivable content pages.

-f FILENAME is optional. The extension (.zip or .esb) will be appended to the name and does not need to be included. The default filename is “edgeCore-export-” followed by a timestamp.

Adding the -l arg will add the logs to the backup.

Use -p PAGES (where PAGES is a comma-separated list of content pages) to create a partial backup. Note that the server will prepend “/Content Menu/” to all paths, so it is assumed that all folders and pages fall under the Content Menu.
Example: Assume the menu structure is as follows:

/Content Menu/
  Admin Content/
    Welcome
  Demo Data/
    DemoPage1
    DemoPage2
  MyMapsPage

-p “Demo Data/” will create a partial archive containing the Demo Data folder and all of its content.
-p “Demo Data/DemoPage1, MyMapsPage” will contain the Demo Data folder with only DemoPage1, as well as MyMapsPage.
-p MyMapsPage will contain only MyMapsPage.
Note that if any of the folder or page names contain spaces, the value of the -p arg must be wrapped in quotes.

-c (coerce) option is required if trying to create a backup on a non-admin server within a cluster.

admin
cluster, clu -j | -l | -s | -i

[-a ALIAS]

[-u URL]

Joins or leaves the cluster (must already have shared auth database and configured admin node). Command should be run from an intended content node.

-j | -l | -s | -i: Join or leave or cluster status or cluster id respectively. Must specify exactly one of these options. Status lists information about all nodes in the cluster. ID returns this node’s ID as it relates to the cluster.

-a ALIAS: Alias for this content node. Required for join or leave.

-u URL: URL for this content node. Used with join option. If specified, overrides default URL (http://localhost:8080, or the URL specified by the property edge.cli.url).

admin
config [–rm]

-s SCOPE

-k KEY

[-v VALUE]

View or change config values.

–rm: Optional. Removes the specified config entry.

-s SCOPE: Required. Can be “global” or “group:DOMAIN_NAME”.

-k KEY: Required. The configuration key, e.g. pipeline.safeSubstitution.

-v VALUE: Optional. If included, the value is set for the given key, e.g. true. Otherwise, the current value (if any) will be returned.

admin
edit -s SCOPE

-n NAME

[-e ENDPOINT]

p PROPERTY

[-v VALUE]

Change a connection endpoint, dataset, or account adapter property value. In the context of this command, a dataset is any feed or transform that exists in the edgeSuite pipeline.

-s SCOPE: Required. Can be “connection”, “dataset”, or “accountAdapter”.

-n NAME: Required. Name of the connection, dataset, or accountAdapter to edit.

-e ENDPOINT: Required for “connection” scope. Name of the endpoint on the connection to edit. For connections that support failover, endpoint names can be customized. The default name for main endpoint is “Endpoint1”. Connections that do not support failover (e.g. Server Filesystem) have one endpoint and its name is “Primary”.

-p PROPERTY: Required. The name of the property to edit, e.g. verboselogging. If PROPERTY is set to “*” (including the quotes so as not to be confused with the asterisk wildcard), and the VALUE argument is omitted, the server will return a list of all visible properties of the entity in question.

-v VALUE: Optional. If included, the command will set the property to the value. Otherwise, command will return the current value.

admin
fetch -p PRODUCER

[-v VARS…]

Fetch the data set of a producer (feed or transform), passing in optional node variables.

-p PRODUCER: Required. The name of an existing producer in the edgeCore pipeline.

-v VARS: Optional. If set, provide one or more “varName=varValue” entries to set the node variables for the fetch operation. e.g. -v “foo=bar” “code=1337”

none
health, pm Retrieves a snapshot of the system’s performance metrics (memory and CPU usage), as well as last reboot time. admin
help, h [command] Lists info about commands. If command name is supplied, lists info for the specified command. none
license, lic [-f FILENAME] Echoes edgeSuite server’s licensing information.

If -f FILENAME is included, the server will load the indicated file. FILENAME should point to a license file on the same host as the Edge CLI application.

admin
push [–clear]

[-f FILENAME]

[-d STRING]

FEED

Send text-based data to a feed created from a Push Connection. The data can be read from a file (see -f FILENAME), as a string literal (see -d STRING), or via standard input (using |, <, or manual entry terminated by Ctrl+D).

–clear: Optional. Excludes any data specified by file, string, or standard input. Removes existing data from the specified FEED.

-f FILENAME: Optional. If specified, FILENAME must point to a readable file.

-d STRING: Optional. If STRING contains spaces, it must be wrapped in double quotes.

FEED: Required. Must refer to an existing feed in edgeCore.

Note: If redirecting data to standard input (using | or <), entering one’s password via masked password prompt as mentioned above in “Running Edge CLI” will not be an option. This is due to the fact that redirecting the input starts the JVM in non-interactive mode, which disables the console that is necessary for the password prompt.

admin
restore, res [–list OPTION]

[-r]

[-l OPTION]

[-t TYPE]

[-p PROFILE]

[-c]

-f FILENAME

Restores the archive specified by -f FILENAME. Note that FILENAME can refer to a named archive on the target edgeSuite instance (i.e. any archive name listed when running the restore command with –list archives) or it can be a path to a file anywhere on the same system as the target edgeSuite instance. FILENAME is required unless running the restore command with –list OPTION.

Full (.zip) restore options:
-r: Removes files from the custom folders before restore
-l OPTION: OPTION must be true or false. If false, the restore will preserve the current license. By default, full archives will replace the current license with the license from the archive.
-t TYPE: Restore type: ALL or CONTENT_ONLY (default is ALL). A CONTENT_ONLY restore will leave existing users and groups unaffected.

Partial (.esb) restore options:
-p PROFILE: Restore profile name. See Advanced Options: Restore Profile for further details.

Other options:
–list OPTION: Lists all available archives or restore profiles. OPTION should be set to ‘archives’ or ‘profiles’ accordingly.
-c: Coerce — required if trying to restore an archive on a non-admin server within a cluster

admin
sysinfo, si Retrieves the edgeCore version, Tomcat server version, the server’s endpoints and shutdown port, the install home, Java version, OS, and system time zone. none
version, v Retrieves version info for edgeCore server as well as any installed modules. If server is part of a cluster, will also return configuration version of all edgeCore instances in the cluster. admin

Configuration Settings  #

Edge CLI by default will target an edgeSuite instance running at http://localhost:8080, with connection timeout settings (in seconds) shown below. These settings can be overridden via a properties file.

Property Key
Property Default Value
Description
edge.cli.url http://localhost:8080 Default value for --url option.
edge.cli.connect.timeout 5 TCP connect timeout for HTTP connection.
edge.cli.connect.request.timeout 15 Internal connection request timeout.
edge.cli.socket.timeout 120 TCP socket timeout.  An activity timeout for the socket – once a connection has been established this is how much time can elapse between response packets from the server and the connection be maintained.
ssl.permissive true Trust all SSL certificates.  Set this false for better security – you may then need to configure the trust store.

If running Edge CLI on Mac or Linux, es-cli.sh will automatically set the JVM argument -Dedge.cli.config=${Install_Home}/bin/cli/cli.properties when passing commands to the Edge CLI .jar file.

If running Edge CLI on Windows, edge.cli.config must be explicitly set by the user as shown in the example above.

The URL setting also has a command-line override option (which will override both the default and the properties file settings). To activate this, run es-cli.sh with the option --url HOST, where HOST refers to the preferred target edgeCore server.

Configuring Pre-authenticated Access #

If running Edge CLI and edgeCore together on the same host, the edgeCore server can be configured to allow CLI requests to pass through without requiring a username and password. To do this, a user must be designated in ${Install_Home}/conf/custom.properties to act as the CLI user. This setting looks like:

edge.cli.local.user=someUser@someDomain

Note: authentication without credentials is not supported when running Edge CLI from a remote host.

Exit Codes #

Upon exiting, Edge CLI will return one of the following exit codes. The values and their meanings are loosely based on the BSD exit codes.

Exit Code
Meaning
0 Success
1 General error
64 Command usage error (usually illegal arguments)
69 Service unavailable (this can result from errors with either the requests or the responses)
74 Input/output errors (general I/O errors, JSON reading/mapping errors)
77 Permission denied (usually an authentication failure)
127 Unknown command

Standalone CLI #

It is also possible to remotely deploy and use the CLI to run commands without direct access to the full edgeCore instance. This is available with the Standalone CLI. The Standalone CLI is currently supported on Unix and Mac systems. The Standalone CLI installation files can be downloaded from the following location:

https://share.edge-technologies.com/index.php/s/wmN4QK9bP8KHTLi

Standalone CLI Setup #

Once the CLI package is downloaded and unpacked, it can be used by navigating inside the /StandaloneCLI/bin directory. From there you can run cli commands on remote and local machine by running command in this format:

./es-cli.sh command --user admin --pass admin --url http://instanceUrl/

Example of Standalone CLI Usage on Remote edgeCore Instance #

Uploading files can be done either via curl or scp. In the example we will run curl.

Information about setting up curl or activating it can be found here:

https://help.ubidots.com/en/articles/2165289-learn-how-to-install-run-curl-on-windows-macosx-linux

Once curl is set up, you must run a curl login command, which has this format:

curl -i -X POST -d j_username=youredgeadmin -d j_password=youredgeadminpass -c cookie.txt http://remoteinstanceAdressandPort/j_spring_security_check

Example:

curl -i -X POST -d j_username=admin -d j_password=admin -c cookie.txt http://13.58.167.103:8080/j_spring_security_check

Once the login is completed, you can run upload (POST) commands on a specific file or backup you want delivered to the remote machine:

curl -b cookie.txt -F file=@/pathtoFileonLocalMachine/Backup.zip http://RemoteInstanceAndPort/upload/backup/

Example:

curl -b cookie.txt -F file=@/Users/Joe/TestNew.zip http://13.58.167.103:8080/upload/backup/

Once the file is uploaded, it will be on your remote instance in [Install_Home]/exports. Then you can proceed with running a restore command:

/es-cli.sh restore -f /home/ubuntu/edgeSuite/exports/TestNew.zip -t CONTENT_ONLY  --user admin --pass admin --url http://13.58.167.103:8080/

The backup process is almost the same, but in reverse. First you will run the backup command to create a backup in the exports directory:

./es-cli.sh backup --list  --user admin --pass admin --url http://13.58.167.103:8080/

After that you can run the curl command to retrieve the backup, or any other file to your machine:

curl -b cookie.txt -o FileName.zip http://instanceandPort/download/archive/BackupName.zip

Example:

curl -b cookie.txt -o TestDownload.zip http://13.58.167.103:8080/download/archive/edgeSuite-export-20191226-152459.706.zip