These instructions explain how to register and authenticate with Space and Time using the Space and Time command line interface.

The Space and Time CLI (sxtcli) is a command-line tool for interacting with the Space and Time network from a client computer, such as your laptop or application server. It uses Java to allow cross-platform support, running on Windows, MacOS, or Linux.

📘

Almost all examples in the docs will use the CLI and terminal as the primary tool. The CLI is an easy OS & programming language -agnostic way for developers to connect to Space and Time, but it's not the only way. Check out this page on ways to connect to learn more.

Requirements

1. API Base URL - If you don't know your SxT API URL, you can look it up here.
2. JoinCode (optional) - If you want to join an existing Space and Time subscription, you'll need your organization's JoinCode. You will receive your JoinCode in your Welcome to Space and Time email.

How to Connect to the Space and Time Network via the CLI

Step 1: Download and install the latest JavaJDK

Java is fairly standard install on most development machines. To test if you have Java installed, open a terminal / CMD and enter java --version which should return something like:

└─[$] java --version

java 20.0.1 2023-04-18
Java(TM) SE Runtime Environment (build 20.0.1+9-29)
Java HotSpot(TM) 64-Bit Server VM (build 20.0.1+9-29, mixed mode, sharing)

If the Java version is lower than 20.0.1 or is not installed (returns an error):

1. Navigate to the JavaJDK page
2. Select your OS / Chip Architecture
3. Download the file named: jdk-<latest_version>_*
4. Follow install instructions per the installer for your operating system
5. Once complete, confirm Java is installed by running java --version as per above

Step 2: Install the SxTCLI jar

To install the SXTCLI, there are two steps: download the .jar file, and create a short-cut to the .jar file.

Download the .JAR File

This link to the SxTCLI will take you to a top-level directory with all CLI versions. We highly recommended that you always install the latest version.

Inside the version folder, you'll see two files: .jar and .pom. For most uses, you only need the .jar file, and can ignore the .pom file. Save the downloaded .jar file to the location where you want the application to run (for example, /applications/SXTCLI/, /program files/SXTCLI/, etc).

Once downloaded, you can test the SXTCLI by opening a terminal or command window, navigate to the folder where you saved the .jar, and enter:
java -jar sxtcli-<version>.jar version

You should see a menu returned, something like: Version: 0.0.6

Add CLI to your Shell Environment (optional)

While this step is technically optional, SXTCLI is significantly easier to use if you create an alias or shortcut to the .jar file, rather than always having to call java with a specific location.

Using your editor of choice, edit your shell profile:

Add this line to the bottom, replacing <PathToJar> with the fully qualified path where you saved the downloaded jar file:

alias sxtcli='java -jar <PathToJar>/sxtcli-<LATEST_VERSION>.jar'

📘

While you're editing your shell profile, consider the best practice of setting up a dotenv (.env) file at the same time!

To test your alias, open a new terminal and type: sxtcli version
If the alias is working correctly, you'll see the same answer as the above step: Version: 0.0.6

👍

Congrats! You're ready to begin working with the SXTCLI!

If you're going to be using the SXTCLI extensively, check out this community project that creates additional shell functions to wrap and simplify the most common SXTCLI functions!

Step 3: Set up a dotenv file (optional)

While also technically optional, we recommend that you set up an Environment Variable file, sometimes called a dotenv or ".env" file, to hold local secrets like your UserID and KeyPair. This is a general development best practice, not specific to SxT, however, you will see dotenv files used frequently in SxT docs, SDKs, etc.

See the SxT best practices guide on using a Dotenv File for Secrets.

For the examples below (and almost all others in this documentation), we're assuming environment variables that match those seen here.

Step 4: Register and authenticate

If you are new to SxT and registering a new UserID, you can use this command:

sxtcli authenticate register --url=$API_URL --userId=$USERID --code="<joinCode>"

Note that it doesn't require a keypair - if omitted, it will create a new keypair automatically and print it out. Just be sure to save the keypair before closing the terminal window.

❗️

Please take note of the public and private key and store your private key somewhere safe, like a password manager. Once your terminal window is closed, any information cannot be recovered. Losing your keypair is the same as losing control of your UserID!

If you already have a SxT UserID, you can easily authenticate to the Space and Time network by typing this into your terminal window:

sxtcli authenticate login --url=$API_URL --userId=$USERID --publicKey=$USER_PUBLIC_KEY --privateKey=$USER_PRIVATE_KEY

👍

That's it!

You've successfully registered and authenticated directly to the Space and Time network using the CLI.

There are many other options available using the CLI, including the ability to login, refresh your session, run queries against the SxT Network, add new keypairs to your keychain, manage your subscription, look up past query activity, etc. To see a full list of options, just run sxtcli help