Command Line Interface (CLI)

Scramjet Command Line Interface is run by command-line si for Scramjet Interface.

1. Installing the Scramjet CLI

   npm install -g @scramjet/cli

2. Verify installation
   By running si for Scramjet Interface command in the terminal. Once Scramjet CLI in installed si can be used for the continuation of this installation. Overview of the commands may differ depending on the user's environment settings (production - cloud environment | development - local environment) with the possibility to change every profile environment's setting. More information can be found in section 5.B.4
   

   si

3. For the list of all CLI commands

   si -h or --help

4. Autocompletion
   This will help you auto-complete commands or arguments by typing partial commands or arguments and then pressing the [TAB] key

   si completion install

5. CLI Configuration
   The CLI interface can work in either with the development or production environment. The environment value that is set to production allows to use commands of the Scramjet Cloud Platform. The CLI development environment communicates with the Transform Hub (STH).
   There are 3 Configuration modes:
   A- Default Profile - Contains default values for the Scramjet Transform Hub (STH) settings.
   B- Profile Configuration - Enables the personalization of the property values for the Scramjet Transform Hub (STH) and Scramjet Cloud Platform settings.
   C- Session Configuration - Contains values for the current session.
   

Default Configuration

If not set otherwise the default global configuration file used by all CLI processes would be pre-set to the following:

{
  "configVersion": 1,
  "apiUrl": "http://127.0.0.1:8000/api/v1",
  "middlewareApiUrl": "https://api.scramjet.cloud/api/v1",
  "env": "production",
  "scope": "",
  "token": "",
  "log": {
    "debug": false,
    "format": "pretty"
 }
}

Type in your command-line si config set [command] for editing the default values of each property.

Properties description:

Property	Description	Default value
configVersion	A version of the config.	1
apiUrl	Hub API url. Applicable only to self hosted Hub.	"http://127.0.0.1:8000/api/v1"
middlewareApiUrl	Scramjet Cloud Platform Space url. To be set during authorization process.	""
env	Set the environment you will work in: - "production" → for Scramjet Cloud Platform environment, - "development" → to communicate with Transform Hub (self hosted Hub environment).	"development"
scope	A default scope that should be used when session starts.	""
token	Scramjet Cloud Platform authorization token. To be set during authorization process.	""
log	"log" property contains two additional properties: - "debug" → if error occurs stack trace can be shown/hide with the "true"/"false" option, - "format" → log messages display can be set to "pretty" or "json".	"debug": false "format": "pretty"

Profile Configuration

In this section a user will be able to create, configure, or delete a particular profile from the a list of profiles, taking note that any changes will only be made to the current active profile only.

1. Create a new Profile
   A new profile config file will be created in the same directory as the default configuration file. It will automatically retain the same property values as the default config file. Switching to this new config file will enable the user to edit its value.

   si config profile create <Profile-Name>

2. List all profiles
   The arrow on the left will point out which profile is currently in use.
   

   si config profile list

3. Select or Switch between Profiles
   This command-line will enable the user to select any profile from the listed profiles. The arrow before the profile name will confirm which profile is currently being in use.

   si config profile use <Profile-Name>

4. Edit or Set new values for a specific Profile
   After making sure to be on the right profile the below command will set the newly desired values

   si config set [command]

5. Print Profile values
   In order to view the values of the current active profile

   si config print  or  si c p

6. Reset Profile values
   It is only possible to reset the values of the current profile a user is working on. The reset will assign the original values which were added by default to the profile when it was created.
   

   warning

   No confirmation message will be shown upon execute the reset command
   

   si config reset all

7. Delete or Remove a Profile
   In case the user deleted the current profile, CLI will revert back to the default profile. The command si config profile remove <Profile-Name> will delete the specified profile from the listed profiles.

   si config profile remove <Profile-Name>

8. One-time Profile selection
   A user can attach a particular profile for a specific sequence while sending this Sequence to the Scramjet Cloud Platform (SCP). The following command-line will illustrate how to attach a profile to a Sequence.

   si seq send <path/to/filename.tar.gz> --config <Profile-Name>

Session Configuration

A user can use optionally the hyphen (-) at the end of each command instead of pin-pointing the last Instance-id or the last Sequence-id for a particular configuration, keeping in mind that the hyphen method only retrieves that last Instance-id or the last Sequence-id. Session Configuration is the configuration of an Instance being run in a particular terminal, with this option it enables the user to have different configurations for different terminal sessions. The user must remember that upon closing the terminal all session configurations will be lost. Once created a session configuration json file will be added to the user's local temporary directory under a specific Session-id e.g. /tmp/.si-tmp/4020249/session-config.json. In order for the user to retrieve Sequence-id a sequence must be sent to the Hub which is on Scramjet Cloud Platform and then the Sequence must be started in order to retrieve the Instance-id.

1. Session Info
   To print out the current Session Configurations use the below command
   

   si config session

2. Edit last Instance-Id and last Sequence-Id
   The last Instance-Id and last Sequence-Id values are set automatically once a user runs si seq deploy or si seq send and si seq start commands. They can also be set manually with the following 2 commands:

   si seq use <Sequence-id>
   si inst use <Instance-id>
   info

   Use the hyphen (-) at the end of the command instead of inputting the Sequence-id to retrieve automatically the last Sequence-id.
   

3. Editing the last Space-Id and last Hub-Id
   In order for a user to set manually the Space-id or the Hub-id the following commands must be inputted on the terminal.

   si space use <Space-id>
   si hub use <Hub-id>

Useful Commands

The below commands will briefly introduce the si Command-line tools and functionalities behind each command. More illustration on those commands can be found on Scramjet's Transform Hub CLI GitHub repository.

Scope
The Scope is a tool that helps you manage multiple environments when you have more than just one. Each Scope can contain one Space with one Hub but different Scopes can have same Space-id and different Hub-id which must be already existing inside that particular Space.

si scope [command]

Space
Contains multiple Hubs with their running Sequences as Instances.

si space [command]

Hub
The Scramjet Transform Hub (STH) enables the user to manage the Sequences and Instances deployed in a particular data center, server, or device. Hub monitoring system allows the user to retrieve reports in the real-time concerning logs and loads. All information about the Hub commands can be listed with the following command si hub --help.

si hub [command]

Sequence Store
A centralized location where Sequences can be stored conveniently to ensure their persistance storage. Sequences stored in Sequence Store are accessible by any Hub and can be also run by one or multiple Hubs without having to send them to that particular Hub, whether locally on the user's machine or on Scramjet Cloud Platform.

Store List
This command-line displays the list of Sequences saved in Sequence Store.

si store ls

Store Send
In order to send a Sequence to Sequence Store the following command-line must be executed.

si store send <Sequence-package>

Store Delete
For deleting a Sequence located in the Sequence Store the following command-line must be executed. No prior warning will be issued in case the deleted Sequence is already in use by a particular Hub, since that Hub already acquired the Sequence prior to deletion. It is also possible to restart this Sequence after it has been already deleted on Sequence Store but only if it was previously available on the given Hub.

si store delete <Sequence-id>

Store Help
This command-line will list all possible operations of the Sequence Store.

si store --help

Sequence
Sequences can provide a user with a variety of functionalities ranging from a simple program reading data to more complex and multi-level applications that are able to process a huge amount of data within a short period of time. In both cases they can be simply managed by the following command.

si sequence|seq [command] [options...]

Sequence Packaging
Before starting any Sequence it has to be packaged, which means that the package is archived in a directory with the Sequence and all its required dependencies. After executing this following command a tar.gz file will be created in the same directory as the user is currently at.

si sequence pack <path/to/folder>

Sequence Send
Any Sequence which needs to be run on the Hub must be packaged prior to that in a tar.gz format and the package will be sent to the development or production environment

si sequence send <path/to/filename.tar.gz>

Sequence Start
By sending the packaged Sequence to the Hub and the user will automatically receive a Sequence-id, which enables the user to trigger the start command. The Sequence which will be run will take a form of an Instance and the Instance-id will be automatically generated.

si sequence start <Sequence-id> [options]
si seq start -   // (Hyphen will automatically retain the last Sequence-id)

Sequence Use
In order to assign a desired Sequence-id to a hyphen use the following command-line.

si sequence use <Sequence-id>

Sequence Deploy
By using the deploy command a user will be able to pack, send and start a Sequence in one go with a return info that includes Sequence-id and Instance-id.

si sequence deploy|run [options] <path/to/folder>

Sequence Start/Deploy with arguments
A user can attach additional arguments in an array method to the existing Sequence as follows.

si seq start <Sequence-id> --args=[\"arg1\","\arg2\"]

Or the following command in case the Sequence is not packed.

si seq deploy <path/to/folder> --args=[\"arg1\","\arg2\"]

Sequence Delete
You can delete a single Sequence found on a particular Hub by including its id or use the prune method to remove all the Sequences on a particular Hub, keep in mind a user can not delete a Sequence which is being run unless using the force method, which will kill an Instance of a specified Sequence-id and remove that Sequence. Prune force method will kill all Instances and remove all Sequences of a particular Hub.

si sequence delete|rm <Sequence-id>
si sequence prune -f
si sequence prune // Removes all Sequences but not the Instances and their related Sequences

Sequence Information
This command provides information about the Sequence, such as its id, name, version, etc. Additionally, if the Sequence has any Instances running, there will be an array of Instance-ids included.

si sequence info <Sequence-id>

Instance
Once a Sequence is deployed to Scramjet Cloud Platform (SCP), an Instance is created. One Sequence can be run multiple times, which will result in the creation of many Instances, each with its unique Instance-id. The si inst --help will list all commands for an Instance. An Instance will retain an Instance-id after a Sequence has been started. This command and its sub-commands will allows a user to have full control over the execution of the program/application, also to interact with a running program by delivering or receiving data. Additionally, CLI provides that ability to monitor an Instance.

si instance|inst [command] [options...]

Instance Information
A user can retrieve information as an Object concerning an Instance through the following command.

si instance info <Instance-id>

A user can also use the a Hyphen (-) at the end of the command to retrieve information on the last Instance-id.

si inst info -

For Instance logs use the following command-line.

si inst log <Instance-id>

Instance Output
For a user to be able to view the returned output of a running Sequence the following command must be inputted after making sure that an Instance has been initiated, as long as the Status section under the Instance Information command indicates "completed". If an Instance has been completed, records on its status will only be preserved for 3 minutes from the time of its completion, any command connected to the completed status must be executed within those 3 minutes i.e. Instance output.

si instance output [options] <Instance-id>

Instance Output Saved
A user can save the Instance's output, logs, standard output (stdout) or, standard error (stderr) through the following commands.

si inst output <Instance-id> | tee filename.txt
si inst log <Instance-id> | tee filename.txt
si inst stdout <Instance-id> | tee filename.txt
si inst stderr <Instance-id> | tee filename.txt

Instance Input
In case an input is required for an Instance as standard input (stdin) the following command must be inputted for the Instance to be completed. This input can be extracted from a file path as long as it fulfills the required format of an Instance or through adding it to the command-line itself.

si instance input [options] <Instance-id> [file]
si inst input - <local/path/to/file> -e -t application/octet-stream
            // Hyphen (-) will automatically retrieve the Last Instance-id

Instance Event
An Event has the ability to send a custom command through an API endpoint which is not usually part of the listed commands of Scramjet. An Event extends the functionalities of those commands, a user must define the functionality of this Event i.e. what will happen upon sending an Event to an Instance. An Instance can also send an Event to the API endpoint. Scramjet CLI also supports sending and receiving events. Scramjet Instance Events share the same conceptual grounds as Events in Node.js and Python Event Emitter.

si inst event [command] [options...]

Emit Event
A user can send an Event to an Instance through the following command in order to execute a customized function. Event-Name do not require any quotation marks to be executed in the command-line. A user must create an Event-Name along side its functionality before sending it to a particular Instance. By publishing an Event a user can invoke a function in their Sequence.

si inst emit|invoke [options] <Instance-id> <Event-Name> [payload]

Receive Event
For a user to be able to execute an Event, Event-Name must be also provided in the command without quotations. By executing an Event ON method, the Event-Name will be subscribing to this Event and a function would be invoked each time the named Event is emitted.

si instance event on [options] <Instance-id> <Event-Name>

Topic
Topics provides the ability to send data between Instances. It enables the ability to build highly efficient data streaming pipelines. The topic data pipelines can be used to transfer data between your Instances. Each Instance can be either producer and/or consumer of one topic.

si topic [command] [options...]

Send Topic
Send Topic command allows sending data to a given Topic. If a Topic doesn't exist a new Topic under the requested name will be created. In additional to that, a Topic-Name can be created as a result of a user's source code request or return.

si topic send [options] <Topic-Name> [file]

Get Topic
Retrieves data from a given Topic and prints it out on the terminal, but if this command-line is executed the data of the Topic will be considered as already consumed and it will not be re-consumed by another Instance. If a Topic-Name is non-existing on the list a new Topic-Name will be assigned to this Topic-Name.

si topic get [options] <Topic-Name>

Rename Topic
When starting a Sequence, the Topic can be renamed. The two used cases which can support the renaming of a Topic, is when a topic is provided by the Sequence or when a Topic is required by a Sequence.

si seq start <Sequence-id> --input-topic <Topic-Name>        // when consuming data
si seq start <Sequence-id> --output-topic <New-Topic-Name>   // when producing data

Util
The Util command provides a varieties of functionalities for the user to benefit from. Currently Util enables the user to color format the logs saved in a file. More Util options will be developed in the near future.

si util | u [options] [command]

Util log-format with Coloring
Util log-format option is the functionality responsible for coloring the logs saved in the file. A significant visual improvement which enables a user to have a better, more clear overview of the logs.

si util log-format | lf [options]

Util log-format without Coloring

si util log-format --no-color

---