Stacks CLI

Learn more about the Stacks CLI capabilities

The Stacks CLI enables interactions with the Stacks 2.0 blockchain through a set of commands. At the current stage, the CLI is intended for developer experimentation on the testnet only.

Installation

First, ensure you have npm installed. Next, run the following command in your terminal:

npm install -g @stacks/cli

Network selection

By default, the CLI will attempt to interact with the mainnet of the Stacks 2.0 blockchian. However, it is possible to override the network and set it to the testnet:

stx <command> -tstx <command> -t

By default, using the -t flag causes the CLI to connect to the testnet node at http://stacks-node-api.blockstack.org:20443. To specify a node to connect to, add the -I flag followed by the URL of the node:

stx <command> -I "http://localhost:20443"stx <command> -I "http://localhost:20443"

Account

This section describes how to use the CLI to manage an account.

Creating an account

You can generate a new account for testnet by using the make_keychain command with the -t option:

stx make_keychain -tstx make_keychain -t

Your response should look like this:

{ "mnemonic": "private unhappy random runway boil scissors remove harvest fatigue inherit inquiry still before mountain pet tail mad accuse second milk client rebuild salt chase", "keyInfo": { "privateKey": "381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301", "address": "ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ", "btcAddress": "n4X37UmRZYk9HawtS1w4xRtqJWhByxiz3c", "index": 0 } }{ "mnemonic": "private unhappy random runway boil scissors remove harvest fatigue inherit inquiry still before mountain pet tail mad accuse second milk client rebuild salt chase", "keyInfo": { "privateKey": "381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301", "address": "ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ", "btcAddress": "n4X37UmRZYk9HawtS1w4xRtqJWhByxiz3c", "index": 0 }}

The mnemonic is your 24 word seed phrase which you should back up securely if you want access to this account again in the future. Once lost, it cannot be recovered.

The Stacks address associated with the newly generated account is: ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ

It is best to store the response of the CLI somewhere. You will need the private key, for instance, to send tokens to others.

Checking balance

You can check the balance of your account using the following command:

stx balance ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ -tstx balance ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ -t

The response will look like this:

{ "balance": "10000", "nonce": 0 }{ "balance": "10000", "nonce": 0}

Take note that the nonce for the account is 0. This number is important for transaction broadcasting.

Transactions

This section describes how to use the CLI to generate and broadcast transactions.

Sending Tokens

In order to send tokens, the CLI command requires 5 parameters:

  • Recipient Address: The Stacks address of the recipient
  • Amount: The number of Stacks to send denoted in microstacks (1 STX = 1000000 microstacks)
  • Fee Rate: The transaction fee rate for this transaction. You can safely set a fee rate of 200 for Testnet
  • Nonce: The nonce is a number that needs to be incremented monotonically for each transaction from the account. This ensures transactions are not duplicated
  • Private Key: This is the private key corresponding to your account that was generated when

The CLI command to use with these parameters is send_tokens:

stx send_tokens ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7 1000 200 0 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301 -tstx send_tokens ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7 1000 200 0 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301 -t
{ "txid": "0xd32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c", "transaction": "https://explorer.stacks.co/txid/0xd32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c" }{ "txid": "0xd32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c", "transaction": "https://explorer.stacks.co/txid/0xd32de0d66b4a07e0d7eeca320c37a10111c8c703315e79e17df76de6950c622c"}

With this command we’re sending 1000 microstacks to the Stacks address ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7.

We set the fee rate to 200 microstacks. If you're not sure how much your transaction will cost.

The nonce is set to 0 for this transaction, since it will be the first transaction we send from this account. For subsequent transactions, you will need to increment this number by 1 each time. You can check the current nonce for the account using the balance command.

Finally, the last parameter is the private key for the account. 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301

Once again, we’re using the -t option to indicate that this is a Testnet transaction, so it should be broadcasted to Testnet.

If valid, the transaction will be broadcasted to the network and the command will respond with a transaction ID.

Previous
Stacking
Next
Local development
Powered by