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 as the primary tool. The CLI is the easiest 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 version is lower than 20.0.1 or Java 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: Download and run SxTCLI jar

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 to download the .jar file, not the .pom file. Save the downloaded file to the location of your choice.

To test, open a terminal / CMD, navigate to the folder where you saved the .jar, and enter:
java -jar sxtcli-<version>.jar help

You should see a menu returned, something like:

└─[$] java -jar sxtcli-<version>.jar help   
                                    
Usage: <main class> [COMMAND]
Commands:
  help          Display help information about the specified command.
  authenticate  Perform platform authentication commands.
  biscuit       Perform biscuit commands.
  discover      Perform resource discovery commands.
  sql           Perform SQL commands.
  sql-support   Perform supporting SQL commands.

Step 3: Add the CLI to your shell environment (optional)

Creating a shell alias for running the SxT CLI is recommended for ease of use. Adding an alias to your shell depends on your operating system.

Mac OSX & Linux

Using your editor of choice, edit your shell profile:

Add this line:

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

Optionally: Aliases defined above can be referenced further down in the same profile script. For instance, if you save your user secrets to a common .env file, you can add another line to the end of your shell profile file, allowing you to login to Space and Time with one command: sxtlogin

sxtlogin() {
    . ~/Path/to/my/.env
    ACCESS_TOKEN=$(sxtcli authenticate login --url=$API_URL --userId=$USERID --publicKey=$USER_PUBLIC_KEY --privateKey=$USER_PRIVATE_KEY | awk 'NR==2{ print $2 }' )
    echo $ACCESS_TOKEN
}

🚧

You must reload your shell or open a new terminal to properly load new aliases. Also, if you're on OSX and you want to level up your shell game, check out OhMyZsh.

Windows

For instructions on adding the CLI to your PATH environment variable on Windows, see this resource.

Test CLI execution

To test that your installation was successful, open a terminal / CMD from any folder location, and run the command sxtcli help
If done correctly, you can now run sxtcli from anywhere.

Step 4: Set up a dotenv file (optional)

While 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 5: 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