The SXTCLI is a great tool for developers to get started with Space and Time. It provides you a quick, programmatic way to interact with the Space and Time network and perform more complex actions, without being dependent on any particular programming language or IDE.

Let's Get Started!

To be able to validate your script, we'd ask that you generate a new file called Install_the_CLI.sh that you can commit to your branch of the SXT-Community/SXTAccreditation repo at the end of the activity.

Install Java JDK

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):

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 --version as per above

Install and Configure SXTCLI

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:

Mac OSX	Linux	Windows WSL
~/.zshrc	~/.bash_profile	~/.bashrc

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!

Add New Keypair with SXTCLI

Assuming you're following along on the accreditation track, you've probably created your UserID through the Space and Time Studio application, but do not yet have an ED25519 public/private keypair. Adhering to security best practices, private keys are always generated locally (on your computer) so only the public key needs to be transmitted. Here, Studio cannot help.

This is where SXTCLI comes in handy - the CLI can not only generate new keypairs, but can register new keypairs with the Space and Time network such that the private key is never transmitted (challenge / response model).

Adding a new ED25519 keypair to your account requires authenticating once (to verify you are in control of the UserID) then registering the locally generated public key. We'll use Space and Time Studio to authenticate and provide the ACCESS_TOKEN, which proves we are in control of the account. Then we can use that ACCESS_TOKEN and the SXTCLI to validate our account and register a new keypair.

To add a new ED25519 keypair to your account:

Make sure the Space and Time CLI is installed.
Open a terminal / command window and enter: sxtcli authenticate keypair
...which should produce an output similar to...
```
ED25519 KeyPair (base64)
Private key: ft2oz41+aXy1KtAyNzGOqxnHGbNSSXV8xpxN6FpN8w=
Public key:  eIMaJpSbLC6jyAG9RfwvklgsXbDc/HI2eH7TitL2pA=
```
Note: do not use the above keys - for proper security, please always generate your own new keys.
STOP NOW and save your new keys to a secure repository, such as an enterprise secrets manager or password manager. Like web3 wallets, lost keys cannot be recovered!
Navigate to Space and Time Studio, click on "Sign In" in the upper-right most corner, and log in with the same UserID which will receive the new keypair association.
Click on "My Account" in the upper-right (replaces "Sign In") and make sure you're on the "My Account" tab.
Scroll down to the section titled, "Quickly test out our API from Docs" and copy the "Access Token" show at the bottom:

Return to your terminal window and use the SXTCLI to complete the registration process:
```
sxtcli authenticate keychain \
--accessToken="eyJ0eXBlIjoiYWNjZXNzIiwia2lkIjoiZTUxNDVkYmQtZGNmYi00ZjI4LTg3NzItZjVmNjN..." \
--url="https://api.spaceandtime.dev" \
add \
--privateKey="ft2oz41taXy1KtAyNzGOqxnHGbNSSXV8xpxN6FpN8w=" \
--publicKey="eIMaJpSbLC6jyAG9RfwvklgsXbDcdHI2eH7TitL2pA="
```
1. Paste your ACCESS_TOKEN over the sample in line 2
2. Paste your Private Key over the sample in line 5
3. Paste your Public Key (wallet address) over the sample in line 6
4. All other parameters can be left to default

If successful, you'll receive the message: key added to keychain.

👍
Congrats! You've successfully added a new keypair to your UserID's keychain!

You can add as many keypairs to your keychain as you'd like. For more information, check out this detailed article on connecting to the decentralized network.

🚧
To align with security best practices, Space and Time will never transmit your private key. Some tools like the SXTCLI will require your private key to cryptographically sign authentication challenge tokens, but that private key itself is never transmitted.

Login with SXTCLI

To login to the Space and Time network using the CLI, make sure you've installed the Space and Time CLI and have a valid space and time user, then copy/paste the commands below into a terminal:

Replace placeholders below with your credentials and copy/paste the below SXTCLI command into a terminal:

sxtcli authenticate login \
  --url="https://api.spaceandtime.dev" \
  --userId="your_userid" \
  --publicKey="your_public_key" \
  --privateKey="your_private_key"

API_URL="https://api.spaceandtime.dev"
USERID="your_userid"
USER_PUBLIC_KEY="your-public-key"
USER_PRIVATE_KEY="your-private-key"

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

This command will return two tokens:

ACCESS_TOKEN - used to authenticate any API calls to the network, expires after 25 minutes
REFRESH_TOKEN - used to request a new ACCESS_TOKEN, expires after 30 minutes

🚧
An ACCESS_TOKEN is an authenticated session to the Space and Time network - to keep yourself secure, please treat your ACCESS_TOKEN as a secure key and do not share with others.

Optionally, it's a good idea to copy the ACCESS_TOKEN to an environment variable. This can be done manually, i.e., ACCESS_TOKEN="eyJ0eXBlIjoiY..." or if on Linux / MacOS, by directing the CLI output to a parser like awk:

ACCESS_TOKEN=$( \
  sxtcli authenticate login \
  --url="https://api.spaceandtime.dev" \
  --userId="your_userid" \
  --publicKey="your_public_key" \
  --privateKey="your_private_key" 
| awk 'NR==2{ print $2 }' )

API_URL="https://api.spaceandtime.dev"
USERID="your_userid"
USER_PUBLIC_KEY="your-public-key"
USER_PRIVATE_KEY="your-private-key"

ACCESS_TOKEN=$( \
  sxtcli authenticate login \
  --url=$API_URL \
  --userId=$USERID \
  --publicKey=$USER_PUBLIC_KEY \
  --privateKey=$USER_PRIVATE_KEY
| awk 'NR==2{ print $2 }' )

Optionally, let's test our ACCESS_TOKEN by submitting a request to the network. Assuming your ACCESS_TOKEN is stored in an environment variable as described above, you can request details on your UserID, or run queries.

curl --request POST \
--url "https://api.spaceandtime.app/v1/sql" \
--header "accept: application/json" \
--header "authorization: Bearer $ACCESS_TOKEN" \
--header "content-type: application/json" \
--data '{
    "sqlText": "Select count(*) as Blocks_Yesterday from Ethereum.Blocks where time_stamp between current_date-1 and current_date"
}'

curl --request GET \
     --url https://api.spaceandtime.app/v1/auth/validtoken \
     --header 'accept: application/json' \
     --header "authorization: Bearer $ACCESS_TOKEN"

👍
Contrats, you've authenticated to the Space and Time network and generated an ACCESS_TOKEN using the CLI!

Hint: If you plan to use the CLI frequently, you might consider:

It's a best practice to store user secrets in a dotenv (.env) file
Check out this this community project for CLI shortcuts

Run a Query with SXTCLI

To run a query in the SXTCLI directly, you need at least the following information:

The Space and Time network API endpoint - by default, this is: https://api.spaceandtime.dev
The ACCESS_TOKEN generated by logging in or creating a new account
The SQL text to execute

Assuming we have the above information set to environment variables, a simple query to calculate the number of blocks created on Ethereum over the last 3 days looks like:

SQL="Select cast(time_stamp as date) as Block_Date, count(*) as Block_Count from ZKSYNCERA.BLOCKS where time_stamp between current_date-3 and current_date group by 1 order by 1"

sxtcli sql --url=$API_URL --accessToken=$ACCESS_TOKEN --sqlText="$SQL"

Output:

[ {
  "BLOCK_DATE" : "2024-10-19",
  "BLOCK_COUNT" : 72120
}, {
  "BLOCK_DATE" : "2024-10-20",
  "BLOCK_COUNT" : 74705
}, {
  "BLOCK_DATE" : "2024-10-21",
  "BLOCK_COUNT" : 76162
}, {
  "BLOCK_DATE" : "2024-10-22",
  "BLOCK_COUNT" : 1
} ]

👍
Congrats! You've just run a query on Space and Time!

If you are running queries against permissioned (aka private) tables, you will also need a biscuit.

Get Credit:

You'll get credit for this activity if you:

Login with the CLI
Run the Query against ZKSYNCERA.BLOCKS exactly as shown above
Commit your work file to the SXT-Community/SXTAccreditation repo

How should I commit my branch changes?

When you're complete with the activity, simply commit your changes to your branch of work, then push to the SXT-Community/SXTAccreditation repo. Many IDEs have automated processes to manage this for you, but to do this manually by opening a temrinal / WSL window, and typing:

Line 1: Change to your work folder in your SXT-Community/SXTAccreditation directory
Line 2: Make sure your branch is active
Line 3: Add all changed files to your local stage
Line 4: Commit your changes
Line 5: Push your commited changes to github!

cd ./your/path/SXTAccreditation/<your_folder>
git checkout <your_branch>
git add .  
git commit -m "added my new working file"
git push

If you get an error on line 5 saying, The current branch stephens_work has no upstream branch, this is because Github doesn't know about your branch yet. Simply run the command the git tool recommends - it will look something like:
git push --set-upstream origin <your_branch>

When you're done for the day, head over to SXT-Community/SXTAccreditation/Pulls page on Github, and (if you're logged in) you'll see a message like:

Click on the button above to create a Pull Request, give us some feedback in the description, and click "Create Pull Request". Done!