NEAR CLI
The NEAR Command Line Interface (CLI) is a tool that enables to interact with the NEAR network directly from the shell. Among other things, the NEAR CLI enables you to:
- Login with a NEAR account
- Deploy a contract
- Interact and query information from a deployed contract
Under the hood, NEAR CLI utilizes the NEAR JavaScript API
The NEAR CLI also comes with an implementation in Rust called near-cli-rs
.
If you want to use near-cli
while you have near-cli-rs
installed, prefix the following commands with npx
.
Overview
Click on a command for more information and examples.
Command | Description |
---|---|
ACCESS KEYS | |
near add-credentials | Stores credentials for an account locally |
near add-key | adds a new access key to an account |
near delete-key | deletes an access key from an account |
near generate-key | generates a key pair and optionally stores it locally as credentials for an accountId |
near list-keys | displays all access keys and their details for a given account |
near login | stores a full access key locally using NEAR Wallet |
ACCOUNTS | |
near create-account | creates a new account, either using a faucet to fund it, or an account saved locally |
near delete-account | deletes an account and transfers remaining balance to a beneficiary account |
near list-keys | displays all access keys for a given account |
near send-near | sends tokens from one account to another |
near state | shows general details of an account |
CONTRACTS | |
near call | makes a contract call which can invoke change or view methods |
near deploy | deploys a smart contract to the NEAR blockchain |
near storage | Shows the storage state of a given contract, i.e. the data stored in a contract |
near view | makes a contract call which can only invoke a view method |
TRANSACTIONS | |
near tx-status | queries a transaction's status by txHash |
Setup
Installation
Make sure you have a current version of
npm
andNodeJS
installed.
Mac and Linux
- Install
npm
andnode
using a package manager likenvm
as sometimes there are issues using Ledger due to how OS X handles node packages related to USB devices. [click here] - Ensure you have installed Node version 12 or above.
- Install
near-cli
globally by running:
npm install -g near-cli
For example, on Ubuntu 20.04 near-cli
can be installed by running:
# Install nvm (https://github.com/nvm-sh/nvm?tab=readme-ov-file#installing-and-updating)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
# Install node
nvm install node
# Install near-cli
npm install -g near-cli
# near-cli works!
near --help
Windows
For Windows users, we recommend using Windows Subsystem for Linux (
WSL
).
- Install
WSL
[click here] - Install
npm
[click here] - Install
Node.js
[ click here ] - Change
npm
default directory [ click here ]- This is to avoid any permission issues with
WSL
- This is to avoid any permission issues with
- Open
WSL
and installnear-cli
globally by running:
npm install -g near-cli
Network selection
The default network for
near-cli
istestnet
.
- You can change the network by prepending an environment variable to your command.
NEAR_NETWORK=testnet near send ...
- Alternatively, you can set up a global environment variable by running:
export NEAR_NETWORK=mainnet
- All commands that interact with the network also allow to pass the
--networkId
option.
near send-near ... --networkId mainnet
Custom RPC server selection
You can set custom RPC server URL by setting these env variables:
NEAR_MAINNET_RPC
NEAR_TESTNET_RPC
Clear them in case you want to get back to the default RPC server.
Example:
export NEAR_TESTNET_RPC=<put_your_rpc_server_url_here>
Access Keys
All keys are stored locally at the root of your HOME
directory:
~/.near-credentials
(MAC / Linux)C:\Users\YOUR_ACCOUNT\.near-credentials
(Windows)
Inside .near-credentials
, access keys are organized in network subdirectories: testnet
, and mainnet
.
These network subdirectories contain .JSON
objects with an:
account_id
private_key
public_key
near add-credentials <accountId>
Stores credentials (full-access-key) locally for an already existing account.
- arguments:
accountId
- options:
--seedPhrase
or--secretKey
Examples:
near add-credentials example-acct.testnet --seedPhrase "antique attitude say evolve ring arrive hollow auto wide bronze usual unfold"
near add-key
Adds either a full access or function access key to a given account.
Optionally allows to sign with a Ledger:
--signWithLedger
--ledgerPath
Note: You will use an existing full access key for the account you would like to add a new key to. (near login
)
1) add a full access
key
- arguments:
accountId
publicKey
Example:
near add-key example-acct.testnet Cxg2wgFYrdLTEkMu6j5D6aEZqTb3kXbmJygS48ZKbo1S
Example Response
Adding full access key = Cxg2wgFYrdLTEkMu6j5D6aEZqTb3kXbmJygS48ZKbo1S to example-acct.testnet.
Transaction Id EwU1ooEvkR42HvGoJHu5ou3xLYT3JcgQwFV3fAwevGJg
To see the transaction in the transaction explorer, please open this url in your browser
https://testnet.nearblocks.io/txns/EwU1ooEvkR42HvGoJHu5ou3xLYT3JcgQwFV3fAwevGJg
2) add a function call
key
- arguments:
accountId
publicKey
--contract-id
- options:
--method-names
--allowance
accountId
is the account you are adding the key to
--contract-id
is the contract you are allowing methods to be called on
--method-names
are optional and if omitted, all methods of the--contract-id
can be called.
--allowance
is the amount of Ⓝ the key is allowed to spend on gas fees only (default: 0).
Note: Each transaction made with this key will have gas fees deducted from the initial allowance and once it runs out a new key must be issued.
Example:
near add-key example-acct.testnet GkMNfc92fwM1AmwH1MTjF4b7UZuceamsq96XPkHsQ9vi --contract-id example-contract.testnet --method-names example_method --allowance 30000000000
Example Response
Adding function call access key = GkMNfc92fwM1AmwH1MTjF4b7UZuceamsq96XPkHsQ9vi to example-acct.testnet.
Transaction Id H2BQL9fXVmdTbwkXcMFfZ7qhZqC8fFhsA8KDHFdT9q2r
To see the transaction in the transaction explorer, please open this url in your browser
https://testnet.nearblocks.io/txns/H2BQL9fXVmdTbwkXcMFfZ7qhZqC8fFhsA8KDHFdT9q2r
near delete-key
Deletes an existing key for a given account. Optionally allows to sign with a Ledger:
--signWithLedger
--ledgerPath
- arguments:
accountId
publicKey
- options:
--networkId
,force
Note: You will need separate full access key for the account you would like to delete a key from. (near login
)
Example:
near delete-key example-acct.testnet Cxg2wgFYrdLTEkMu6j5D6aEZqTb3kXbmJygS48ZKbo1S
Example Response
Transaction Id 4PwW7vjzTCno7W433nu4ieA6FvsAjp7zNFwicNLKjQFT
To see the transaction in the transaction explorer, please open this url in your browser
https://testnet.nearblocks.io/txns/4PwW7vjzTCno7W433nu4ieA6FvsAjp7zNFwicNLKjQFT
near generate-key
Displays a key-pair and seed-phrase and optionally stores it locally in
.near-credentials
.
- arguments:
accountId
ornone
- options:
--fromSeedPhrase
,--saveImplicit
,--queryLedgerPK
Note: There are several ways to use generate-key
that return very different results. Please reference the examples below for further details.
1a) near generate-key
Creates and displays a key pair
near generate-key
Example Response
Seed phrase: antique attitude say evolve ring arrive hollow auto wide bronze usual unfold
Key pair: {"publicKey":"ed25519:BW5Q957u1rTATGpanKUktjVmixEmT56Df4Dt9hoGWEXz","secretKey":"ed25519:5StmPDg9xVNzpyudwxT8Y72iyRq7Fa86hcpsRk6Cq5eWGWqwsPbPT9woXbJs9Qe69crZJHh4DMkrGEPGDDfmXmy2"}
Implicit account: 9c07afc7673ea0f9a20c8a279e8bbe1dd1e283254263bb3b07403e4b6fd7a411
1b) near generate-key --saveImplicit
Creates and displays a key pair, saving it locally in
.near-credentials
as an implicit account.
near generate-key --saveImplicit
Example Response
Seed phrase: antique attitude say evolve ring arrive hollow auto wide bronze usual unfold
Key pair: {"publicKey":"ed25519:BW5Q957u1rTATGpanKUktjVmixEmT56Df4Dt9hoGWEXz","secretKey":"ed25519:5StmPDg9xVNzpyudwxT8Y72iyRq7Fa86hcpsRk6Cq5eWGWqwsPbPT9woXbJs9Qe69crZJHh4DMkrGEPGDDfmXmy2"}
Implicit account: 9c07afc7673ea0f9a20c8a279e8bbe1dd1e283254263bb3b07403e4b6fd7a411
Storing credentials for account: 9d6e4506ac06ab66a25f6720e400ae26bad40ecbe07d49935e83c7bdba5034fa (network: testnet)
Saving key to '~/.near-credentials/testnet/9d6e4506ac06ab66a25f6720e400ae26bad40ecbe07d49935e83c7bdba5034fa.json'
2) near generate-key accountId
Creates a key pair locally in
.near-credentials
with anaccountId
that you specify.
Note: This does NOT create an account with this name.
near generate-key example.testnet
Example Response
Seed phrase: antique attitude say evolve ring arrive hollow auto wide bronze usual unfold
Key pair: {"publicKey":"ed25519:BW5Q957u1rTATGpanKUktjVmixEmT56Df4Dt9hoGWEXz","secretKey":"ed25519:5StmPDg9xVNzpyudwxT8Y72iyRq7Fa86hcpsRk6Cq5eWGWqwsPbPT9woXbJs9Qe69crZJHh4DMkrGEPGDDfmXmy2"}
Implicit account: 9c07afc7673ea0f9a20c8a279e8bbe1dd1e283254263bb3b07403e4b6fd7a411
Storing credentials for account: example.testnet (network: testnet)
Saving key to '~/.near-credentials/testnet/example.testnet.json'
3a) near generate-key --fromSeedPhrase="your seed phrase"
Uses a seed phrase to display a public key and implicit account
near generate-key --seedPhrase="antique attitude say evolve ring arrive hollow auto wide bronze usual unfold"
Example Response
Seed phrase: antique attitude say evolve ring arrive hollow auto wide bronze usual unfold
Key pair: {"publicKey":"ed25519:BW5Q957u1rTATGpanKUktjVmixEmT56Df4Dt9hoGWEXz","secretKey":"ed25519:5StmPDg9xVNzpyudwxT8Y72iyRq7Fa86hcpsRk6Cq5eWGWqwsPbPT9woXbJs9Qe69crZJHh4DMkrGEPGDDfmXmy2"}
Implicit account: 9c07afc7673ea0f9a20c8a279e8bbe1dd1e283254263bb3b07403e4b6fd7a411
3b) near generate-key accountId --seedPhrase="your seed phrase"
Will store the key pair corresponding to the seedPhrase in .near-credentials
with an accountId
that you specify.
Example Response
Seed phrase: antique attitude say evolve ring arrive hollow auto wide bronze usual unfold
Key pair: {"publicKey":"ed25519:BW5Q957u1rTATGpanKUktjVmixEmT56Df4Dt9hoGWEXz","secretKey":"ed25519:5StmPDg9xVNzpyudwxT8Y72iyRq7Fa86hcpsRk6Cq5eWGWqwsPbPT9woXbJs9Qe69crZJHh4DMkrGEPGDDfmXmy2"}
Implicit account: 9c07afc7673ea0f9a20c8a279e8bbe1dd1e283254263bb3b07403e4b6fd7a411
4a) near generate-key --queryLedgerPK
Uses a connected Ledger device to display a public key and implicit account using the default HD path (
"44'/397'/0'/0'/1'"
)
near generate-key --queryLedgerPK
You should then see the following prompt to confirm this request on your Ledger device:
Make sure to connect your Ledger and open NEAR app
Getting Public Key from Ledger...
After confirming the request on your Ledger device, a public key and implicit accountId will be displayed.
Example Response
Using public key: ed25519:B22RP10g695wyeRvKIWv61NjmQZEkWTMzAYgdfx6oSeB2
Implicit account: 42c320xc20739fd9a6bqf2f89z61rd14efe5d3de234199bc771235a4bb8b0e1
3b) near generate-key --queryLedgerPK --ledgerPath="HD path you specify"
Uses a connected Ledger device to display a public key and implicit account using a custom HD path.
near generate-key --queryLedgerPK --ledgerPath="44'/397'/0'/0'/2'"
You should then see the following prompt to confirm this request on your Ledger device:
Make sure to connect your Ledger and open NEAR app
Waiting for confirmation on Ledger...
After confirming the request on your Ledger device, a public key and implicit accountId will be displayed.
Example Response
Using public key: ed25519:B22RP10g695wye3dfa32rDjmQZEkWTMzAYgCX6oSeB2
Implicit account: 42c320xc20739ASD9a6bqf2Dsaf289z61rd14efe5d3de23213789009afDsd5bb8b0e1