=nil; CLI

The =nil; CLI offers a convenient way for interacting with the cluster by abstracting over JSON-RPC methods.

The CLI can also be integrated into a CI/CD pipeline. For example, a pipeline may retrieve certain values from a contract and then use the received data in subsequent commands.

This page lists all commands exposed by the =nil; CLI as well as their flags and arguments.

Global flags

The following flags can be used with any command.

Flag	Definition
`--quiet \| -q`	Enable quiet mode (the CLI will only output values with no additional text).
`--verbose \| -v`	Enable verbose mode (the CLI will attach additional explanatory text to every output).
`--help \| -h`	Receive help for the CLI.

The following flags can be used without a command.

Flag	Definition
`--config \| -c`	Specify the path to the =nil; CLI config file.
`--log-level \| -l`	Set the =nil; CLI logging level. Possible values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.
`--help \| -h`	Receive help for the command.

`block`

Description

This command allows for reading block information.

Subcommands

No subcommands.

Flags

Flag	Definition
`--shard-id ShardId`	Specify the id of the shard from which the block should be retrieved.

Examples

Retrieve a block by hash

nil block BLOCK_HASH [--shard-id SHARD_ID; default 1]

Retrieve a block by number

nil block BLOCK_NUMBER [--shard-id SHARD_ID; default 1]

Retrieve the latest block

nil block latest [--shard-id SHARD_ID; default 1]

Output

Fetched block:
{
  "hash": "{BLOCK_HASH}",
  "inMessagesRoot": "{IN_MESSAGE_ROOT}",
  "messages": [MESSAGES],
  "number": {BLOCK_NUMBER},
  "parentHash": "{PARENT_HASH}",
  "receiptsRoot": "{RECEIPTS_ROOT}",
  "shardId": {BLOCK_HASH}
}

`completion`

Description

This command generates autocompletion scripts for various shells.

Subcommands

Subcommand	Definition
`bash`	Generate the autocompletion script for `bash`.
`fish`	Generate the autocompletion script for `fish`.
`powershell`	Generate the autocompletion script for `powershell`.
`zsh`	Generate the autocompletion script for `zsh`.

Example

nil completion bash | fish | powershell | zsh

Output

COMPLETION_SCRIPT

`config`

Description

This command is for setting up the =nil; CLI.

Subcommands

Subcommand	Definition
`get`	Gets the value of the provided config key.
`set`	Sets the given value to the provided config key.
`init`	Initializes the =nil; CLI config file.
`show`	Shows the current contents of the =nil; CLI config file.

Examples

Initialize the config file

nil config init

Set a config value

nil config set KEY VALUE

Read a config value

nil config get KEY

Show the contents of the config file

nil config show

Outputs

Initializing the config file

Config initialized successfully: config.yaml

Setting a config value

Set "KEY" to "VALUE"

Getting a config value

KEY: Value

Showing the contents of the file

Config file: config.yaml
KEY: VALUE
...

`contract`

Description

This command is for reading contract information and for interacting with smart contracts via external messages.

Subcommands

Subcommand	Definition
`address`	Calculate the smart contract address given its bytecode.
`balance`	Retrieve the balance of the smart contract.
`call-readonly`	Call a smart contract method via an external message.
`code`	Retrieves the smart contract bytecode.
`currencies`	Retrieves the currencies mapping of the smart contract.
`deploy`	Deploys the smart contract.

Flags

For address:

Flag	Definition
`--abi string`	The path to the `.abi` file containing the contract ABI.
`--salt Uint256`	Arbitrary salt.
`--shard-id ShardId`	The ID of the shard where the contract is located/could be located.

For call-readonly:

Flag	Definition
`--abi string`	The path to the `.abi` file containing the contract ABI.
`--fee-credit Uint256`	The fee credit for the call.

For deploy:

Flag	Definition
`--abi string`	The path to the `.abi` file containing the contract ABI.
`--no-wait`	Prevents waiting for the deployment message receipt when the command is executing.
`--salt Uint256`	Arbitrary salt.
`--shard-id ShardId`	The ID of the shard where the contract is located/could be located.

Examples

Calculate the smart contract address

nil contract address path/to/contract.bin [--abi path/to/contract.abi] [--no-wait] [--salt SALT] [--shard-id SHARD_ID; default 1]

Call a smart contract method

nil contract call-readonly CONTRACT_ADDRESS CALLDATA | METHOD_NAME [--abi path/to/contract.abi] [--fee-credit FEE_CREDIT]

Deploy a smart contract

nil contract deploy path/to/contract.bin [--abi path/to/contract.abi] [--no-wait] [--salt SALT] [--shard-id SHARD_ID; default 1]

Retrieve the code of a smart contract

nil contract code CONTRACT_ADDRESS

Retrieve the balance of a smart contract

nil contract balance CONTRACT_ADDRESS

Retrieve the currencies of a smart contract

nil contract currencies CONTRACT_ADDRESS

Outputs

Calculating the smart contract address

Contract address: CONTRACT_ADDRESS

Calling a smart contract method

Call results: CALL_RESULTS

Deploying a contract

Contract address: CONTRACT_ADDRESS

Retrieving the code of a smart contract

Contrace code: CONTRACT_CODE

Retrieving the contract balance

Contract balance: CONTRACT_BALANCE

Retrievign the contract currencies

Contract currencies: CONTRACT_CURRENCIES

`help`

This command is for receiving help for the =nil; CLI.

Subcommands

No subcommands.

Flags

No flags.

Example

nil help

Output

CLI tool for interacting with the =nil; cluster

Usage:
  nil [command]

Available Commands:
  block       Retrieve a block from the cluster
  completion  Generate the autocompletion script for the specified shell
  config      Configuration management
  contract    Interact with contract on the cluster
  help        Help about any command
  keygen      Generate a new key or generate a key from a provided hex private key
  message     Retrieve a message from the cluster
  minter      Interact with minter on the cluster
  receipt     Retrieve a receipt from the cluster
  system      Request system-wide information
  wallet      Interact with wallet on the cluster

Flags:
  -c, --config string      Path to config file (default "config.yaml")
  -h, --help               help for nil
  -l, --log-level string   Log level: trace|debug|info|warn|error|fatal|panic (default "trace")
  -q, --quiet              Quiet mode (print only the result and exit)
  -v, --verbose            Verbose mode (print logs)

`keygen`

This command is for generating private keys.

Subcommands

Subcommand	Definition
`fromHex string`	Generate a new key from the provided hex of a private key.
`new`	Generate a new key.

Examples

Generate a new key from hex

nil keygen fromHex HEX

Generating a new key

nil keygen new

Output

Private key: PRIVATE_KEY

`message`

This command is for retrieving a message from the cluster.

Subcommands

No subcommands.

Flags

Flag	Definition
`--shard-id ShardId`	Specify the id of the shard from which the message should be retrieved.

Example

nil message MESSAGE_HASH [--shard-id SHARD_ID; default 1]

Output

Fetched message:
{
    "blockHash": "{BLOCK_HASH}",
    "blockNumber": BLOCK_NUMBER,
    "chainId": "{CHAIN_ID}",
    "from": "{ADDRESS_FROM}",
    "gasLimit": "{GAS_LIMIT}",
    "gasPrice": "{GAS_PRICE}",
    "gasUsed": "{GAS_USED}",
    "hash": "{MESSAGE_HASH}",
    "index": "{INDEX}",
    "seqno": "{SEQUENCE_NUMBER}",
    "signature": "{SIGNATURE}",
    "success": SUCCESS,
    "to": "{ADDRESS_TO}",
    "value": "{VALUE}"
    "data": "DATA"
}

`minter`

This command is for interacting with the =nil; currency minter.

Subcommands

Subcommand	Definition
`create-currency`	Create a new currency and, optionally, withdraw it.
`mint-currency`	Mint an existing currency and, optionally, withdraw it.
`withdraw-currency`	Withdraw an existing currency that has been minted.

Flags

For create-currency, mint-currency:

Flag	Definition
`--withdraw`	Immediately withdraw the created/minted currency to its owner.

Examples

Create a new token

nil minter create-currency OWNER_ADDRESS AMOUNT NAME [--withdraw]

Mint an existign token

nil minter mint-currency OWNER_ADDRESS AMOUNT [--withdraw]

Withdraw tokens

nil minter withdraw-currency OWNER_ADDRESS AMOUNT TO_ADDRESS

Outputs

Creating a new token

Created NAME:AMOUNT CurrencyId=[CURRENCY_ID]

Minting a new token

Minted AMOUNT CurrencyId=[CURRENCY_ID]

Withdrawing tokens

Transferred AMOUNT to TO_ADDRESS CurrencyId=[CURRENCY_ID]

`receipt`

This command is for retriving the receipt with the given hash.

Subcommands

No subcommands.

Flags

Flag	Definition
`--shard-id ShardId`	Specify the id of the shard from which the receipt must be retrieved.

Example

nil receipt MESSAGE_HASH [--shard-id SHARD_ID; default 1]

Output

Fetched receipt:
{
  "blockHash": "{BLOCK_HASH}",
  "blockNumber": BLOCK_NUMBER,
  "bloom": "{BLOOM}",
  "contractAddress": "{CONTRACT_ADDRESS}",
  "gasUsed": GAS_USED,
  "logs": [],
  "messageHash": "{MESSAGE_HASH}",
  "messageIndex": INDEX,
  "outMsgIndex": OUT_MESSAGE_INDEX,
  "success": SUCCESS
}

`system`

This command is for retrieving system information.

Subcommands

Subcommand	Definition
`chain-id`	Retreive the ID of the current chain.
`gas-price`	Retrieve the gas price in the specified shard.
`shards`	Retrieve a list of all execution shards.

Examples

Retrieve the ID of the current chain

nil system chain-id

Retrieve the gas price at the specified shard

nil system gas-price shard-id SHARD_ID

Retrieve the list of all execution shards

nil system shards

Output

Retrieving the ID of the current chain

ChainId: CHAIN_ID

Retrieving the gas price at the specified shard

Gas price of shard SHARD_ID: GAS_PRICE

Retrieving the list of all execution shards

List of shard id:
* SHARD_ID
* SHARD_ID
...

`wallet`

This command is for interacting with wallets.

Subcommands

Subcommand	Definition
`balance`	Retrieves the balance of the wallet specified in the =nil; CLI config.
`call-readonly`	Performs a read-only 'dry run' call to the specified address.
`deploy`	Deploys a smart contract via the wallet.
`info`	Retrives the wallet's address and the public key.
`new`	Create a new wallet.
`send-message`	Send a message to a deployed smart contract via the wallet.
`send-tokens`	Send tokens to the wallet.
`top-up`	Request a 'top up' from the faucet.

Flags

For call-readonly:

Flag	Definition
`--abi string`	Specify the path to the `.abi` file for the contract.
`--fee-credit Uint256`	Set the call fee credit.
`--in-overrides string`	Set the input state overrides.
`--out-overrides string`	Set the output state overrides.
`--with-details`	Define whether the output should show the tokens used and outbound messages.

For deploy:

Flag	Definition
`--abi string`	Specify the path to the `.abi` file for the contract.
`--amount Uint256`	Set the amount of tokens to send to the contract.
`--currency Uint256`	Set the amount of contract currency to generate (cannot be used with the `--no-wait` flag).
`--no-wait`	Define whether the command should wait for the message receipt.
`--salt Uint256`	Set the salt for the deployment message.
`--shard-id ShardId`	Specify the shard where the contract should be deployed.

For new:

Flag	Definition
`--amount Uint256`	Set the initial balance of the wallet (capped at 10 000 000)
`--salt Uint256`	Set the salt for the deployment message.
`--shard-id ShardId`	Specify the shard where the wallet should be deployed.

For send-message:

Flag	Definition
`--abi string`	Specify the path to the `.abi` file for the contract.
`--amount Uint256`	Set the amount of tokens to send to the contract.
`--fee-credit Uint256`	Set the message fee credit.
`--no-wait`	Define whether the command should wait for the message receipt.
`--token stringArray`	Define the tokens to transfer to the contract. Tokens are set using the `CURRENCY_ID=AMOUNT` format. The flag accepts can accept multiple tokens.

For send-tokens:

Flag	Definition
`--fee-credit Uint256`	Set the message fee credit.
`--no-wait`	Define whether the command should wait for the message receipt.
`--token stringArray`	Define the tokens to transfer to the contract. Tokens are set using the `CURRENCY_ID=AMOUNT` format. The flag accepts can accept multiple tokens.

Examples

View the wallet balance

nil wallet balance

Perform a read-only call

nil wallet call-readonly ADDRESS [--abi path/to/contract.abi] [--fee-credit FEE_CREDIT] [--in-overrides IN_OVERRIDES] [--out-overrides OUT_OVERRIDES] [--with-details]

Deploy a smart contract

nil wallet deploy path/to/contract.bin [ARGS] [--abi path/to/contract.abi] [--amount AMOUNT] [--currency TOKENS_AMOUNT] [--no-wait] [--salt SALT] [shard-id SHARD_ID]

Send tokens to a smart contract

nil send-tokens ADDRESS [--fee-credit FEE_CREDIT] [--no-wait] [--token stringArray]

Request a 'top up'

nil wallet top-up AMOUNT

Retrieve wallet information

nil wallet info

Create a new wallet

nil wallet new [--amount AMOUNT] [--salt SALT] [--shard-id SHARD_ID]

Send a message to a smart contract

nil wallet send-message ADDRESS BYTECODE | METHOD [ARGS] [--abi path/to/contract.abi] [--amount AMOUNT] [--fee-credit FEE_CREDIT] [--no-wait] [--token TOKENS]

Outputs

Viewing the wallet balance

Contract balance: BALANCE

Performing a read-only call

STATUS, result:
TYPE: VALUE

Deploying a smart contract

Contract address: ADDRESS
Transaction hash: TRANSACTION_HASH

Creating a new wallet

Contract ADDRESS balance is topped up by AMOUNT
Contract address: ADDRESS
Transaction hash: TRANSACTION_HASH
New wallet address: ADDRESS

Sending a message to a smart contract

Transaction hash: TRANSACTION_HASH

Retrieving wallet information

Address: ADDRESS
Public key: PUBKEY

Requesting a 'top up'

Contract ADDRESS balance is topped up by AMOUNT
Contract balance: BALANCE

Sending tokens to a smart contract

Transaction hash: TRANSACTION_HASH

=nil; CLI

Global flags​

block​

Description​

Subcommands​

Flags​

Examples​

Retrieve a block by hash​

Retrieve a block by number​

Retrieve the latest block​

Output​

completion​

Description​

Subcommands​

Example​

Output​

config​

Description​

Subcommands​

Subcommands​

Examples​

Initialize the config file​

Set a config value​

Read a config value​

Show the contents of the config file​

Outputs​

Initializing the config file​

Setting a config value​

Getting a config value​

Showing the contents of the file​

contract​

Description​

Subcommands​

Flags​

Examples​

Calculate the smart contract address​

Call a smart contract method​

Deploy a smart contract​

Retrieve the code of a smart contract​

Retrieve the balance of a smart contract​

Retrieve the currencies of a smart contract​

Outputs​

Calculating the smart contract address​

Calling a smart contract method​

Deploying a contract​

Retrieving the code of a smart contract​

Retrieving the contract balance​

Retrievign the contract currencies​

help​

Subcommands​

Flags​

Example​

Output​

keygen​

Subcommands​

Examples​

Generate a new key from hex​

Generating a new key​

Output​

message​

Subcommands​

Flags​

Example​

Output​

minter​

Subcommands​

Flags​

Examples​

Create a new token​

Mint an existign token​

Withdraw tokens​

Outputs​

Creating a new token​

Minting a new token​

Withdrawing tokens​

receipt​

Subcommands​

Flags​

Example​

Output​

Global flags

`block`

Description

Subcommands

Flags

Examples

Retrieve a block by hash

Retrieve a block by number

Retrieve the latest block

Output

`completion`

Description

Subcommands

Example

Output

`config`

Description

Subcommands

Subcommands

Examples

Initialize the config file

Set a config value

Read a config value

Show the contents of the config file

Outputs

Initializing the config file

Setting a config value

Getting a config value

Showing the contents of the file

`contract`

Description

Subcommands

Flags

Examples

Calculate the smart contract address

Call a smart contract method

Deploy a smart contract

Retrieve the code of a smart contract

Retrieve the balance of a smart contract

Retrieve the currencies of a smart contract

Outputs

Calculating the smart contract address

Calling a smart contract method

Deploying a contract

Retrieving the code of a smart contract

Retrieving the contract balance

Retrievign the contract currencies

`help`

Subcommands

Flags

Example

Output

`keygen`

Subcommands

Examples

Generate a new key from hex

Generating a new key

Output

`message`

Subcommands

Flags

Example

Output

`minter`

Subcommands

Flags

Examples

Create a new token

Mint an existign token

Withdraw tokens

Outputs

Creating a new token

Minting a new token

Withdrawing tokens

`receipt`

Subcommands

Flags

Example

Output

`system`