avalanche-cli
v2.6.2
Published
A command line interface for Avalanche APIs
Downloads
314
Maintainers
Readme
A Command Line Interface for Avalanche APIs
Usage: avalanche-cli [OPTIONS] COMMAND
Options
-h --help Show help information and quit.
-v --version Print CLI version information and quit.
Installation
First of all, it is possible to run avalanche-cli
without any installation whatsoever, by simply invoking it via npx
(aka the npm
package executor):
$ npx avalanche-cli --help
But, if you decide to permanently install it via npm
, then do so with:
$ npm install avalanche-cli -g ## avoid `sudo` (see FAQ)
$ avalanche-cli -h ## show help info
Also, an installation via npm
activates command line completion (i.e. hitting the TAB key after writing avalanche-cli
should offer a list of available commands and options). Finally, for avalanche-cli
to work properly your operating system needs to provide the dependencies below.
Dependencies
Name : curl
Version : 7.73.0-1
Description : An URL retrieval utility and library
Name : zsh
Version : 5.8-1
Description : the Z shell
Or instead of zsh
:
Name : bash
Version : 5.0.018-1
Description : The GNU Bourne Again shell
Optional:
Name : bash-completion
Version : 2.11-1
Description : Programmable completion for the bash shell
Only for installation (and for npx
):
Name : npm
Version : 6.14.8-2
Description : A package manager
Usage
All CLI options of the avalanche-cli
tool can also be set via environment variables. It assumes by default an AVAX node available at https://api.avax.network
– although this can be changed by setting and exporting the AVAX_NODE
variable or by using the corresponding --node
(-N
) option.
JSON processing with jq
Since avalance-cli
does not process any JSON reponses, it is recommended to use the excellent jq
command line JSON processor to handle them. For example:
$ avalanche-cli info peers -YS | jq .result.peers[0]
{
"ip": "52.139.201.134:48452",
"publicIP": "52.139.201.134:9651",
"nodeID": "NodeID-DueWyGi3B9jtKfa9mPoecd4YSDJ1ftF69",
"version": "avalanche/1.3.2",
"up": true,
"lastSent": "2021-05-01T18:33:38Z",
"lastReceived": "2021-05-01T18:33:38Z",
"benched": []
}
..where the -S
(--silent-rpc
) option tells the internal curl
tool to not produce unnessary output, so we get the desired result from above. ;D
Common Options
All commands share the following options and corresponding environment variables:
${AVAX_NODE-https://api.avax.network}
or --node
(-N
)
Can be used to set the AVAX node which the avalanche-cli
tool will be communicating with – where the default is https://api.avax.network
. For example:
$ avalanche-cli info peers -N=https://api.avax.network
$ avalanche-cli info peers --node=https://api.avax.network
$ AVAX_NODE=https://api.avax.network avalanche-cli info peers
${AVAX_YES_RUN_RPC}
or --yes-run-rpc
(-Y
)
Can be used to actually execute the curl
request the avalanche-cli
tool puts together – where by default this is off, i.e. the corresponding curl
request will only be shown but not executed. For example:
$ avalanche-cli info peers -Y
$ avalanche-cli info peers --yes-run-rpc
$ AVAX_YES_RUN_RPC=1 avalanche-cli info peers
${AVAX_SILENT_RPC}
or --silent-rpc
(-S
)
Can be used to make a curl
request with its corresponding silent flag on – where by default it is off. However when on, this will not silence the actual response (if there is any):
$ avalanche-cli info peers -YS
$ avalanche-cli info peers -Y --silent-rpc
$ AVAX_SILENT_RPC=1 avalanche-cli info peers -Y
${AVAX_VERBOSE_RPC}
or --verbose-rpc
(-V
)
Can be used to make a curl
request with its corresponding verbose flag on – where by default it is off. This is useful, if one wants to get a detailed view of an ongoing request:
$ avalanche-cli info peers -YV
$ avalanche-cli info peers -Y --verbose-rpc
$ AVAX_VERBOSE_RPC=1 avalanche-cli info peers -Y
Common Variables
Further, almost all commands share the following – very general – environment variables:
${AVAX_ARGS_RPC}
Can be used to make a curl
request with a corresponding argument (or arguments). This is useful, since it allows to access all of curl
's capabilities. For example:
$ export AVAX_ARGS_RPC="--no-progress-meter" ## if supported by curl implementation
$ avalanche-cli info peers -Y
Now, each request will be performed without a progress meter (which can be distracting in case one chooses to pipe a response through another command).
${AVAX_PIPE_RPC}
Can be used to pipe a curl
response through a command, where AVAX_PIPE_RPC
needs to be an (implicit) associative array with content types as keys and corresponding commands as value entries. For example:
$ export AVAX_PIPE_RPC="declare -A AVAX_PIPE_RPC=([content-type:application/json]='jq -c')"
$ avalanche-cli info peers -Y
Now, each application/json
response will be compactified and colorized by using the jq
command line JSON processor. Further, to temporarily omit piping through any command, (unset or) set AVAX_PIPE_RPC
to an empty string:
$ AVAX_PIPE_RPC='' avalanche-cli info peers -Y
${AVAX_AUTH_HEADER}
An authorization token provides access to one or more API endpoints. This is is useful for delegating access to a node's APIs. Tokens expire after 12 hours, but before that the token can be provided in the header of an API call. Specifically, the header Authorization
should have the value Bearer $TOKEN
. For example:
AVAX_AUTH_TOKEN=$(avalanche-cli auth new-token -p "$AVAX_AUTH_PASSWORD" -e '*' -Y | jq -r .result.token)
export AVAX_AUTH_HEADER="Bearer $AVAX_AUTH_TOKEN"
Any subsequent requests will have the Authorization
header set to Bearer $AVAX_AUTH_TOKEN
, after which – if desired – the header variable can be unset and the token be revoked with:
unset AVAX_AUTH_HEADER
avalanche-cli auth revoke-token -p "$AVAX_AUTH_PASSWORD" -t "$AVAX_AUTH_TOKEN" -Y
FAQ
Can I install as a regular user instead as root
?
It is actually recommended to avoid an installion as root
(or via sudo
). Instead, setup npm
to install packages globally (per user) without breaking out of the $HOME
folder:
$ export PATH="$PATH:$HOME/.node/bin" ## *also* put this e.g. into ~/.bashrc
$ echo 'prefix = ~/.node' >> ~/.npmrc ## use ~/.node for global npm packages
$ npm install avalanche-cli -g ## no sudo required
$ avalanche-cli -h ## show help info
While the recommendation above holds true for GNU/Linux users, it probably may be skipped for macOS users. Further, zsh
users may also need to adjust the instructions accordingly (since they are for bash
users).
How to enable zsh
completions?
Enable zsh
's bash
completion script compatiblity mode, by appending the snippet below to your .zshrc
configuration:
# Use compatiblity mode for bash completions
if [[ -e $HOME/.bash_completion ]]; then
autoload bashcompinit && bashcompinit
source $HOME/.bash_completion
fi
Copyright
© 2024 Moorhead LLC