Nocturnal Prancing Mosquito
    Wondering what’s next for npm?Check out our public roadmap! »

    avalanche-cli

    1.4.0 • Public • Published

    NPM version Build Status

    A Command Line Interface for Avalanche APIs

    Usage: avalanche-cli [OPTIONS] COMMMAND
    

    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).

    Copyright

    (c) 2021, Hasan Karahan, MSc in CS, ETH Zurich. Twitter: @notexeditor.

    Install

    npm i avalanche-cli

    DownloadsWeekly Downloads

    4

    Version

    1.4.0

    License

    BSD-3-Clause

    Unpacked Size

    428 kB

    Total Files

    111

    Last publish

    Collaborators

    • avatar