The SpaceXpanse Command Line Interface (spacexpanse-cli) program is a CLI for interacting with the SpaceXpanse daemon and SpaceXpanse wallets through JSON-RPC.

Much of what can be done in spacexpanse-cli can also be done in the SpaceXpanse QT wallet's console. However, there are advantages to using spacexpanse-cli instead of the QT console. As such, much of the SpaceXpanse documentation uses spacexpanse-cli.

The following is to help you get up to speed on how to use spacexpanse-cli. If you are already comfortable with CLIs, then you can simply run it with the -? or --help parameters to get the information you need and skip this tutorial. That help is the official reference material.

This tutorial is designed as a relaxing walk through that you can follow along with and experiment with as you read. Take time to run some of the commands and see how they work for you. Experience is a great teacher.

Much of what you will need to know about commands and JSON-RPC methods is already documented in Bitcoin documentation. This tutorial is not a substitute for upstream documentation.

If you haven't already, download the SpaceXpanse QT wallet software here and extract the contents of the ZIP file.

• spacexpanse-cli
• spacexpanse-hash
• spacexpanse-qt
• spacexpanse-tx
• spacexpansed

On Linux you'll need to chmod +x them to make them executable.

Here we'll run spacexpansed instead of one of the wallet software packages. Run it with the server command.

spacexpansed -server=1

For more information about options, see Running spacexpansed for Games here and Daemon Options.

Open a console (command prompt in Windows or terminal in Linux) and navigate to the spacexpanse-cli folder.

You can get help for spacexpanse-cli options with this command:

spacexpanse-cli -?

Run that now and have a quick glance.

At the top of the help you'll see some usage cases. Here we'll only examine the first one:

spacexpanse-cli [options] <command> [params]

The [options] are from the help that you just viewed. (The list of commands is available from the SpaceXpanse QT or Electron wallet console by typing "help".) For many commands we don't need to specify any options and can simply send a command with parameters. Here are some examples. They are all are perfectly safe to use, so feel free to try them right now.

spacexpanse-cli getblockcount
spacexpanse-cli getdifficulty
spacexpanse-cli getblockchaininfo
spacexpanse-cli getblockhash 123
spacexpanse-cli gettxoutsetinfo
spacexpanse-cli uptime
spacexpanse-cli game_sendupdates "g/mv" "2aed5640a3be8a2f32cdea68c3d72d7196a7efbfe2cbace34435a3eef97561f2" "3b365d712d87e354a36a6b0445fd022322e559bb9b4dc493f8eea3328d670197"
spacexpanse-cli trackedgames
spacexpanse-cli trackedgames "add" "mv"

As above, these are safe commands and you won't do any damage by using them. We'll warn you for commands that have real consequences.

To interact with SpaceXpanse with zero fear, you can run regtest. See the Regtestnet tutorial for information about that. For now, we return back to the real world mainnet.

The options we saw above are for spacexpanse-cli. It passes those options on to the SpaceXpanse daemon. Some of the options that you will need most include:

• -testnet
• -regtest
• -rpcwallet=<walletname>
• -rpcuser=<user>
• -rpcpassword=<pw>

Commands are JSON-RPC methods defined in spacexpansed. You can get a complete list of commands from the console in either the SpaceXpanse QT or Electron wallet by typing "help".

Commands "do things".

Commands can put data onto the blockchain, get data from the blockchain, manage wallets, and much more. Skim through the spacexpansed-help.txt file to get a feel for the kinds of commands that are available to you. Most are the same as those in bitcoind.

Also consult SpaceXpanse RPC Methods for SpaceXpanse-specific RPC methods.

For more in-depth information on specific methods, you must use the SpaceXpanse QT or Electron wallet console. Run "help <command name>". So, for example, if you want information about creating new addresses, use this:

help getnewaddress

You can also check the Bitcoin documentation for commands as much of it is the same.

Whether or not you need options depends upon what starting options were passed to the wallet software when it started up, or any options that were set inside the spacexpanse.conf file in the data directory. You can find spacexpanse.conf in the data directory here on Windows, Linux, and Mac OS X, respectively:

%appdata%\SpaceXpanse\spacexpanse.conf
~/.spacexpanse/spacexpanse.conf
~/Library/Application Support/SpaceXpanse/spacexpanse.conf

When working with real wallets, such as the Electron game wallet, we must specify which wallet to use with the -rpcwallet=<walletname> option.

To load a wallet.dat file, specify which one similar to any of the following commands.

spacexpanse-cli loadwallet "wallet.dat"
spacexpanse-cli loadwallet "game.dat"
spacexpanse-cli loadwallet "vault.dat"

The following command gets the balance from the game wallet and vault wallet, respectively.

spacexpanse-cli -rpcwallet=game.dat getbalance
spacexpanse-cli -rpcwallet=vault.dat getbalance

This will not cause the wallet to appear in the Electron UI, but it will make the wallet available to the SpaceXpanse daemon, which is what spacexpanse-cli is querying.

You can get a list of currently loaded wallets using the following command:

spacexpanse-cli listwallets

The result after having loaded the 3 wallets above would be as follows.

[
  "vault.dat",
  "game.dat",
  "wallet.dat"
]

You can unload a wallet as shown below:

spacexpanse-cli unloadwallet "wallet.dat"

Now that we've looked a bit at wallets, let's do some cooler stuff starting with backing up a wallet. For this, we must specify the wallet to back up with a spacexpanse-cli option, e.g. "-rpcwallet=game.dat". We must also specify a complete path, e.g. "C:\SpaceXpanse Backups\MyFirstBackup.dat". Make certain that the folder exists.

spacexpanse-cli -rpcwallet=game.dat backupwallet "C:\SpaceXpanse Backups\MyFirstBackup.dat"

Now that we have a backup of our game wallet, let's do some more cool stuff like creating a new address.

spacexpanse-cli -rpcwallet=game.dat getnewaddress "This is my new address!"

The command will run and then return an address, e.g. "CXTdDBYrZEmSHWrsq8hFv5R78NrH8Q2Bxd".

You can now load your Electron wallet and verify that the address is in there. Check the Receive tab and scroll down. Addresses are listed alphabetically by label. (You'll need to shut down spacexpansed, start Electron, check, close Electron, then run spacexpansed as above if you decide to check and then continue on in this tutorial.)

Any cryptocurrency will let you do that; it's very basic. However, there are methods that you won't find in any other cryptocurrencies, other than perhaps some in Namecoin and Huntercoin. But even those don't have all the options you have in SpaceXpanse.

NOTE: This operation costs ROD and is permanent on the blockchain.

If your or your user don't already have a name, you can register one for them. For users, you would normally do this inside of your game through the RPC interface. Let's get you a new name! Replace "Bugs Bunny" with the name you'd like to have.

spacexpanse-cli -rpcwallet=game.dat name_register "p/Bugs Bunny" "{}"

The parameters are:

• Name: "p/Bugs Bunny"
• Value: "{}"

The name must have a namespace. For player accounts this is "p/". Everything after that is the "name" per se. Refer to Name and Value Restrictions for more information.

The value must be valid JSON. In this case we simply send an empty value. There's no reason to do more than that if the goal is to simply register a name. However, it could include an initial move in a game. (Refer to Moves for the "move" specification.)

The return value for that command was "1e57a1136711e008f5046025613c1835515eb7adf175a15bab8a52b3eec28e5f". You can verify this on the SpaceXpanse blockchain by using spacexpanse-cli, or you can check the SpaceXpanse blockchain explorer here.

As mentioned above, you can get more help on the name_register operation with help name_register in the QT or Electron console.

To see all the names in your wallet, use the name_list RPC method. Make sure to specify which wallet you want to check.

spacexpanse-cli -rpcwallet=game.dat name_list

We've taken a leisurely journey into examining spacexpanse-cli. We walked through different kinds of examples. In some examples we used options for spacexpanse-cli and in others we didn't need any options. We looked at several generic commands that are also found in Bitcoin. We also looked at some commands that are specific to SpaceXpanse.

The techniques you learned above through examples can be applied more generally. Check the documentation for the options and commands as shown above.

Remember to check the regtestnet tutorial to find out how you can experiment in a private blockchain without fear of making a mistake.

See more information about SpaceXpanse RPC methods here.

See more information about daemon options for spacexpansed here.

See more information about running spacexpansed for games here.

See more information about spacexpanse.conf here.