Run Commands with the CLI

The VSL command-line interface (CLI) allows you to interact with the VSL server through commands following 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.

Prerequisites

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

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

• A clone of the VSL CLI repository.

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.

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.

Execute 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

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. For example:

target/release/vsl-cli --help

Starting the VSL CLI in REPL mode

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

To switch to REPL mode, run the following:

$ 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 want 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.