Get Started with the CLI (via Decentralized Network)
CLI allows for interactive communication with Space and Time network.
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
- API Base URL - If you don't know your SxT API URL, you can look it up here.
- 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):
- Navigate to the JavaJDK page
- Select your OS / Chip Architecture
- Download the file named:
jdk-<latest_version>_* - Follow install instructions per the installer for your operating system
- Once complete, confirm Java is installed by running
java --versionas 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:
| Mac OSX | Linux |
|---|---|
| ~/.zshrc | ~/.bash_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 a set of SXTCLI shortcuts that wrap the CLI functions, check out:
SXTCLI Wrapper Functions
The SxT CLI is an easy way to interact with the Space and Time network in an ad-hoc and platform agnostic way. That said, it can be a LOT of repetitive typing, if used frequently.
To speed things up, several SxT power-users put together a set of shell function wrappers and environment variable presets, allowing for a faster development and more concise examples. For install instructions and overview, check out the Github repo: SXTCLI_Wrapper_Functions
Along with dotenv files to hold credentials, these shortcuts reduce this:
sxtcli sql --url="https://api.spaceandtime.app" \
--accessToken="eyJ0eXBlIjoiYWNjZXNzIiwia2lkIjoiZTUxNDVkYmQtZGNmYi00ZjI4LTg3NzItZjVmNjNlMzcwM2JlIiwiYWxnIjoiRVMyNTYifQ.eyJpYXQiOjE3MTU3MjY5NDAsIm5iZiI6MTcxNTcyNjk0MCwiZXhwIjoxNzE1NzI4NDQwLCJ0eXBlIjoiYWNjZXNzIiwidXNlciI6InN0ZXBoZW4iLCJzdWJzY3JpcHRpb24iOiIzMWNiMGI0Yi0xMjZlLTRlM2MtYTdhMS1lNWRmNDc4YTBjMDUiLCJzZXNzaW9uIjoiZjcyYjliZTcxODI4ODNkNTc3N2I5NTkyIiwic3NuX2V4cCI6MTcxNTgxMzM0MDUxNywiaXRlcmF0aW9uIjoiNjhmMzcwYTFhZThhZWQzZGM3MDAwZjQyIn0.bPSCUToWWjYU01BUT9UxgFNYdeFJ1lRYQQZu2w0t5jFjMz1mQBFYK7meN40m6NMF4VBqoeaeJ2byb4UXBE13lw" \
--resources="POLYGON.BLOCKS" \
--biscuits="EqQCCrkBCg5zeHQ6Y2FwYWJpbGl0eQoKZG1sX2luc2VydAoVbWVzaF9wcm9kLmlkX3Nlc3Npb25zCgpkbWxfdXBkYXRlCglkbWxfbWVyZ2UKCmRtbF9kZWxldGUKCmRxbF9zZWxlY3QYAyIPCg0IgAgSAxiBCBIDGIIIIg8KDQiACBIDGIMIEgMYgggiDwoNCIAIEgMYhAgSAxiCCCIPCg0IgAgSAxiFCBIDGIIIIg8KDQiACBIDGIYIEgMYgggSJAgAEiAnOAk6_3WmUrrOMVouRm9YO_FraIjHDhGyHi3BUTt2PRpALyb8usHvFOHcH6VDiQ6bTws-xdsGbeYDtCTqkW-rwOXnXZcVpGUuCf_UH700IWVwhOxL6j69JT0767v5iWyWAiIiCiClDcW58xZyyJJ2HZ5CUystv1A7575mmZgNZ-69_WcZXQ==" \
--sqlText="SELECT * FROM POLYGON.BLOCKS limit 10" \
dql --format=TABLE
...to this...
sxtdql "SELECT * FROM POLYGON.BLOCKS limit 10"
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
Updated 4 months ago