Spotflow CLI Overview

The Spotflow CLI is a command-line interface tool that enables you to manage your Spotflow IoT Platform assets. Common use cases include configuring data flows for your devices, creating new Streams within a Stream Group, and routing data to an SQL Egress Sink.

You can use the CLI as a standalone tool or in combination with other command-line tools (e.g CLIs for managing cloud resources) and scripting languages to automate your Platform configuration and operation workflows.

Installation

Download the latest binary executable file for your operating system:

• Windows (Portable Windows x64)
• Linux (Portable Linux x64 - most desktop distributions like CentOS, Debian, Fedora, Ubuntu, and derivatives)
• macOS (Portable macOS x64 - Minimum OS version is macOS 10.12 Sierra)

You can run the downloaded CLI tool from the command line, but it can only be executed within the folder where it was downloaded.

Alternatively, you can add it to your system's PATH, which allows you to run the tool from any location in your command line without specifying its full path. Adding it to your system's PATH can vary depending on your operating system:

Linux

1. Place the CLI in a directory: Put the binary tool in a directory. For instance, create a folder called ~/.spotflow-cli and place it there.

2. Edit your shell's profile file: You can typically add the binary's directory to your PATH by editing your ~/.bashrc, ~/.bash_profile, or ~/.profile file.

   Add the following line to the profile file, replacing /path/to/your/directory with the actual path:

   export PATH="/path/to/your/directory:$PATH"

3. Reload the profile: To apply the changes without logging out, run the following command:

   • For Bash: source ~/.bashrc or source ~/.bash_profile

4. Verify the Installation: Open a new terminal window and try running the tool command spotf --version.

Windows

1. Place the CLI binary file in a directory: Put the binary tool in a directory. For example, create a folder called C:\Users\<YourUsername>\.spotflow-cli and place it there.

2. Add the directory to the PATH:

   • Select the search box next to the Start icon and search for the phrase environment variables.
   • Select Edit the system environment variables from the list.
   • The System Properties window should appear with the Advanced tab selected. Click the button Environment Variables at the bottom.
   • Under System variables, select the Path variable in the list and click the button Edit.
   • Add the path to your directory (e.g., C:\Users\<YourUsername>\.spotflow-cli) to the list of the paths. If the system doesn't show the paths as a vertical list, put a semicolon (;) between the existing value and your path.
   • Click OK on all the opened dialog windows to save the changes.

3. Verify the Installation: Open a new command prompt window and try running the tool command spotf --version.

macOS

1. Place the CLI in a directory: Put the binary tool in a directory. For instance, you can create a folder called ~/.spotflow-cli and place it there.

2. Edit your shell's profile file: You can typically add the binary's directory to your PATH by editing your ~/.zshrc, ~/.bashrc or ~/.bash_profile file, depending on the shell you are using (Bash or Zsh).

   Add the following line to the profile file, replacing /path/to/your/directory with the actual path:

   export PATH="/path/to/your/directory:$PATH"

3. Reload the profile: To apply the changes without logging out, run the following command (for the shell you're using):

   • For Bash: source ~/.bashrc or source ~/.bash_profile
   • For Zsh: source ~/.zshrc

4. Verify the Installation: Open a new terminal window and try running the tool command spotf --version.

info

If you added the CLI to your system's PATH in the previous step, run the following commands in a new terminal window.

Basic usage

Invoke the CLI on the command line through the spotf executable. Help is available using the following command:

spotf --help

Login

To begin working with platform assets, you must first log in. While logging in, you will be automatically redirected to the Portal login page in your web browser. Execute the following command:

spotf login

Output example:

LoginStatusMessage: You have been successfully logged in.
Instance: api.eu1.spotflow.io
InstanceUri: https://api.eu1.spotflow.io
TenantId: d8dae8b8-9717-4c55-bbe1-90f7691b62be
Email: john.smith@gmail.com (1517276c-11a9-49a4-b94e-2edd451c5848)
Default
├── Instance: api.eu1.spotflow.io
├── AccountId: john.smith@gmail.com (1517276c-11a9-49a4-b94e-2edd451c5848)
└── Workspace: My Workspace (4f0f891f-8f0e-4578-9967-68f54b231f7e)

• Instance: An arbitrary ID label for the IoT Platform instance. The label serves as an internal configuration variable within the CLI. The instance name is automatically extracted from the instance URI if not provided.
• InstanceUri: The default IoT Platform instance is api.eu1.spotflow.io, unless you are already logged into a different instance. In such cases, the login command without options will connect you to the last instance you were logged into.
• TenantId: The ID of the tenant you are logged into.
• Email: The email address of the user you are logged in as.
• Default: The CLI current context for the commands. It contains the following properties:
  • Instance: The IoT Platform instance where commands will be executed.
  • AccountId: The account under which commands will be executed.
  • Workspace: The current Workspace in which the commands will be executed. If you are a member of exactly one Workspace (e.g. Workspace established in the Portal beforehand), it is automatically selected as the current Workspace by default. Otherwise, you will need to choose one (use spotf workspace use --help for guidance). If you are not a member of any Workspace, you need to create one.

info

We are in the process of adding support for CI/CD, which will be available soon. Currently, user interaction is necessary during the login process.

Create Workspace

If you have not already created a Workspace, execute the following command:

spotf workspace create --name "My Workspace"

If this is your first Workspace, it will automatically become your current Workspace. If you are already a member of multiple workspaces, you must explicitly choose this Workspace using the command:

spotf workspace use --workspace "My Workspace"

Execute command

If you are successfully logged in and your current Workspace is set, you can manage and interact with the Spotflow IoT Platform assets:

spotf stream-group list

All the available commands are listed in the CLI Reference.

Security

For information about various security-related aspects, please see Security page.