No Results
Edge CLI Overview

Overview

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 edgeSuite 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:

es-cli.(sh|bat) [credentials] command [arguments]

where credentials can be:

  • --user username [--pass password]

  • --apikey key

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 before v3.11.1, es-cli.bat does not 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:

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\edgeSuite-3.8.5-GA\bin>java -Dedge.cli.config="C:\opt\edgeSuite-3.8.5-GA\bin\cli\cli.properties" -jar "C:\opt\edgeSuite-3.8.5-GA\bin\cli\edge-cli-3.8.5.jar" --user admin --pass admin sysinfo

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

Pre-authenticated Access

  • From the same host
    If accessing the CLI from the same host running edgeCore and the edgeCore instance has designated a user for CLI access, the username and password arguments can be omitted: bin/es-cli.sh command [arguments]
  • From any host
    The API key can be specified in the cli.properties (or custom.properties or local.properties for the local instance) using edge.cli.apikey. If this property is set, authentication can be left off and the API key will be used for all CLI operations requiring authentication.
    edge.cli.apikey=dHBuaDQwLTVnNWh1NDdzMDdhc3x0Omwtc1hmPnEtXT1aOSx5TlAoNSc1dylu

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 invocation. e.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 “edgeSuite-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 “Demo Data/DemoPage1, MyMapsPage” will contain the Demo Data folder with only DemoPage1, as well as MyMapsPage. -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). A 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 to 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 edgeCore 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 the 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, the 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 the command name is supplied, lists info for the specified command. none
license, lic [-f FILENAME] Echoes edgeCore 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 a 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 edgeCore 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 edgeCore 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. 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 the server is part of a cluster, will also return the configuration version of all edgeCore instances in the cluster. admin

Configuration Settings

Edge CLI by default will target an edgeCore 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 The 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  ${Install_Home}/conf/custom.properties to act like 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 this link.

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 the remote and local machine by running a 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 on this link.

Once you set up cURL, 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

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 to be 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


Terms | Privacy