Run Commands with the CLI

The VSL command-line interface gives you access to the VSL server by allowing you to perform certain operations using commands that follow the format below:

vsl-cli <subject>:<action> [OPTIONS]

Installing the VSL CLI

To get started, you’ll need to install the VSL CLI on your machine.

There are two ways to install the CLI, depending on whether you want to copy the binary to a global location (accessible from anywhere using vsl-cli) or just build it locally.

Prerequisites

For this installation to be successful, you need to have the following:

• You need Rust installed on your local machine. For this, head to the official Rust installation documentation.

• Clone the VSL CLI repository.

Option 1: Install globally using cargo install

This method installs the CLI in release mode and adds it to your system’s $PATH, allowing you to run vsl-cli from any location.

Run the following command from the root of the project:

cargo +nightly install --path

Once installed, you can start using the CLI directly:

vsl-cli --help

Option 2: Build locally in release mode

If you don’t want to install globally, you can build the CLI and run it from the local target directory.

Build the CLI using the following command:

cargo +nightly build --release

After a successful build, the binary will be available at:

target/release/vsl-cli

You can then run commands using the full path, like so:

target/release/vsl-cli --help

Starting the VSL CLI in REPL mode

The REPL (Read-Eval-Print Loop) lets you interactively run VSL commands, which is especially useful for local testing.

To switch to REPL mode, run the following commands:

$ target/debug/vsl-cli repl

You should see a CLI prompt like this:

$ vsl> 

From here, you can run any VSL command interactively.

For example, if you wanted to view your asset balance, you could simply run the following command:

$ vsl> asset:balance --help

You should see an output like this:

Ask for the balance of an asset for the account

Usage:vsl-cli asset: balance [OPTIONS] <ASSET>


Arguments:
  <ASSET>                       


Options:
  -n, --network <NETWORK>       URL to connect to, or name of a known network
  -a, --account <ACCOUNT>       
  -h, --help                    Print help
  -V, --version                 Print version


REPL Commands:
  help                          Show the help message
  history:list                  Show command history
  clear:screen                  Clear the screen
  clear:history                 Clear command history
  exit, quit, bye               Exit the REPL


Navigation:
  ↑ / ↓ arrows                  Browse command history
  Ctrl+C                        Interrupt current input
  Ctrl+D                        Exit REPL
  Tab                           Auto-completion of commands


vsl>

To start working with the VSL, you need to establish a connection to the server.

You can start the VSL server from within the REPL using an external VSL database or a temporary one.

The following steps will guide you through launching a server using a temporary database:

Step 1: Launch the server

server:launch --db=tmp

You should see output similar to:

Local RPC server is spawned, process id: 864822

Step 2: Confirm the network connection

# Inside REPL

network:current

Expected output:

default: http://localhost:55555 -- up

At this point, you're connected to a live local VSL server and ready to run operations against the VSL database.

Running your first commands

Here are a few common commands to help you get started:

1. Create an account

To perform any operation on the database, we first need to set up an account.

Generate a new VSL account:

# Inside REPL

account:create account-name1

To view the current server state, including accounts and assets, run:

server:dump

You should see an output similar to the following:

List all accounts available accounts on this server:

# Inside REPL

account:list

The output should look something like this:

Available accounts:

  account-name1:  0xbC6102CfFfD036d9d2e85a42f71bd2B4b9fab989 
  account-name2:  0xa8Ef9a14650C29265bFabd8CD068456C73197fBD 
  account-name3:  0x1C75C2A2EE41e2f049C202Fb87feeBeA29f5eead

You can also choose to switch between any of these accounts using the command below:

# Inside REPL

account:use account-name1

The output should look something like this:

using account account-name1: 0xbC6102CfFfD036d9d2e85a42f71bd2B4b9fab989

2. Create an asset

Immediately after setting up an account, you can now perform certain actions on the account. One of such actions is creating an asset.

# Inside REPL

asset:create --name asset-name --supply 1000

You should see the following output:

rc67v8b90n87654xc6v78b9n0iu8y7t6r5excrvtbyuni876

You can now request to see all the asset balances that are connected to this account. You can do this by running the following command:

# Inside REPL

asset:balances

You should see the following output:

{
  "rc67v8b90n87654xc6v78b9n0iu8y7t6r5excrvtbyuni876" : "1000."
}

Learn more

This is just a starting point. To explore everything you can do with the CLI, check out the full VSL CLI Reference Guide.