Skip to main content

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
tip

Under the hood, NEAR CLI utilizes the NEAR JavaScript API


info

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.

CommandDescription
ACCESS KEYS
near add-credentialsStores credentials for an account locally
near add-keyadds a new access key to an account
near delete-keydeletes an access key from an account
near generate-keygenerates a key pair and optionally stores it locally as credentials for an accountId
near list-keysdisplays all access keys and their details for a given account
near loginstores a full access key locally using NEAR Wallet
ACCOUNTS
near create-accountcreates a new account, either using a faucet to fund it, or an account saved locally
near delete-accountdeletes an account and transfers remaining balance to a beneficiary account
near list-keysdisplays all access keys for a given account
near send-nearsends tokens from one account to another
near stateshows general details of an account
CONTRACTS
near callmakes a contract call which can invoke change or view methods
near deploydeploys a smart contract to the NEAR blockchain
near storageShows the storage state of a given contract, i.e. the data stored in a contract
near viewmakes a contract call which can only invoke a view method
TRANSACTIONS
near tx-statusqueries a transaction's status by txHash

[ OPTIONS ]

For EVM support see Project Aurora's aurora-cli.


Setupโ€‹

Installationโ€‹

Make sure you have a current version of npm and NodeJS installed.

Mac and Linuxโ€‹

  1. Install npm and node using a package manager like nvm as sometimes there are issues using Ledger due to how OS X handles node packages related to USB devices. [click here]
  2. Ensure you have installed Node version 12 or above.
  3. Install near-cli globally by running:
npm install -g near-cli

Windowsโ€‹

For Windows users, we recommend using Windows Subsystem for Linux (WSL).

  1. Install WSL [click here]
  2. Install npm [click here]
  3. Install Node.js [ click here ]
  4. Change npm default directory [ click here ]
    • This is to avoid any permission issues with WSL
  5. Open WSL and install near-cli globally by running:
npm install -g near-cli

Network selectionโ€‹

The default network for near-cli is testnet.

  • You can change the network by prepending an environment variable to your command.
NEAR_NETWORK=betanet 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 this 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.

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.

  • 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 or none
  • options: --fromSeedPhrase, --saveImplicit

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 an accountId 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.


near list-keysโ€‹

Displays all access keys for a given account.

  • arguments: accountId

Example:

near list-keys client.chainlink.testnet
Example Response

Keys for account client.chainlink.testnet
[
{
public_key: 'ed25519:4wrVrZbHrurMYgkcyusfvSJGLburmaw7m3gmCApxgvY4',
access_key: { nonce: 97, permission: 'FullAccess' }
},
{
public_key: 'ed25519:H9k5eiU4xXS3M4z8HzKJSLaZdqGdGwBG49o7orNC4eZW',
access_key: {
nonce: 88,
permission: {
FunctionCall: {
allowance: '18483247987345065500000000',
receiver_id: 'client.chainlink.testnet',
method_names: [ 'get_token_price', [length]: 1 ]
}
}
}
},
[length]: 2
]


near loginโ€‹

locally stores a full access key of an account you created with MyNEARWallet.

  • arguments: none
  • options: --networkId

Example:

near login

Custom wallet url:

Default wallet url is https://testnet.mynearwallet.com/. But if you want to change to a different wallet url, you can setup the environmental variable NEAR_MAINNET_WALLET or NEAR_TESTNET_WALLET.

export NEAR_TESTNET_WALLET=https://wallet.testnet.near.org/
near login

Accountsโ€‹

near create-accountโ€‹

Creates an account using an existing account or a faucet service to pay for the account's creation and initial balance.

  • arguments: accountId
  • options: --initialBalance, --useFaucet, --useAccount

Examples::

# Creating account using `example-acct.testnet` to fund it
near create-account new-acc.testnet --useAccount example-acct.testnet
# Creating account using the faucet to fund it
near create-account new-acc.testnet --useFaucet

Subaccount example:

near create-account sub-acct.example-acct.testnet --useAccount example-acct.testnet

Example using --initialBalance:

near create-account sub-acct2.example-acct.testnet --useAccount example-acct.testnet --initialBalance 10
Example Response

Saving key to '/HOME_DIR/.near-credentials/default/sub-acct2.example-acct.testnet.json' Account sub-acct2.example-acct.testnet for network "default" was created.


near delete-accountโ€‹

Deletes an account and transfers remaining balance to a beneficiary account.

  • arguments: accountId beneficiaryId
  • options: force

Example:

near delete-account sub-acct2.example-acct.testnet example-acct.testnet
Example Response

Deleting account. Account id: sub-acct2.example-acct.testnet, node: https://rpc.testnet.near.org, helper: https://helper.testnet.near.org, beneficiary: example-acct.testnet Transaction Id 4x8xohER1E3yxeYdXPfG8GvXin1ShiaroqE5GdCd5YxX To see the transaction in the transaction explorer, please open this url in your browser https://testnet.nearblocks.io/txns/4x8xohER1E3yxeYdXPfG8GvXin1ShiaroqE5GdCd5YxX Account sub-acct2.example-acct.testnet for network "default" was deleted.


near send-nearโ€‹

Sends NEAR tokens (โ“ƒ) from one account to another.

  • arguments: senderId receiverId amount

Note: You will need a full access key for the sending account. (near login)

Example:

near send-near sender.testnet receiver.testnet 10
Example Response

Sending 10 NEAR to receiver.testnet from sender.testnet Transaction Id BYTr6WNyaEy2ykAiQB9P5VvTyrJcFk6Yw95HPhXC6KfN To see the transaction in the transaction explorer, please open this url in your browser https://testnet.nearblocks.io/txns/BYTr6WNyaEy2ykAiQB9P5VvTyrJcFk6Yw95HPhXC6KfN


near stateโ€‹

Shows details of an account's state.

  • arguments: accountId

Example:

near state example.testnet
Example Response

{
"amount": "99999999303364037168535000",
"locked": "0",
"code_hash": "G1PCjeQbvbUsJ8piXNb7Yg6dn3mfivDQN7QkvsVuMt4e",
"storage_usage": 53528,
"storage_paid_at": 0,
"block_height": 21577354,
"block_hash": "AWu1mrT3eMJLjqyhNHvMKrrbahN6DqcNxXanB5UH1RjB",
"formattedAmount": "99.999999303364037168535"
}


Contractsโ€‹

near callโ€‹

makes a contract call which can modify or view state.

Note: Contract calls require a transaction fee (gas) so you will need an access key for the --accountId that will be charged. (near login)

  • arguments: contractName method_name { args } --accountId
  • options: --gas --deposit

Example:

near call guest-book.testnet addMessage '{"text": "Aloha"}' --account-id example-acct.testnet
Example Response
Scheduling a call: guest-book.testnet.addMessage({"text": "Aloha"})
Transaction Id FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK
To see the transaction in the transaction explorer, please open this url in your browser
https://testnet.nearblocks.io/txns/FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK
''

near deployโ€‹

Deploys a smart contract to a given accountId.

  • arguments: accountId .wasmFile
  • options: initFunction initArgs initGas initDeposit

Note: You will need a full access key for the account you are deploying the contract to. (near login)

Example:

near deploy --accountId example-contract.testnet --wasmFile out/example.wasm

Initialize Example:

near deploy --accountId example-contract.testnet --wasmFile out/example.wasm --initFunction new --initArgs '{"owner_id": "example-contract.testnet", "total_supply": "10000000"}'
Example Response

Starting deployment. Account id: example-contract.testnet, node: https://rpc.testnet.near.org, helper: https://helper.testnet.near.org, file: main.wasm Transaction Id G8GhhPuujMHTRnwursPXE1Lv5iUZ8WUecwiST1PcKWMt To see the transaction in the transaction explorer, please open this url in your browser https://testnet.nearblocks.io/txns/G8GhhPuujMHTRnwursPXE1Lv5iUZ8WUecwiST1PcKWMt Done deploying to example-contract.testnet


near storageโ€‹

Shows the storage state of a given contract, i.e. the data stored in a contract.

  • arguments: contractName
  • options: --finality, --utf8, --blockId, --prefix

Example:

near storage hello.near-examples.testnet --finality optimistic --utf8
Example Response
[ { key: 'STATE', value: '\x10\x00\x00\x00Passei por aqui!' } ]

near viewโ€‹

Makes a contract call which can only view state. (Call is free of charge)

  • arguments: contractName method_name { args }
  • options: default

Example:

near view guest-book.testnet getMessages '{}'
Example Response
View call: guest-book.testnet.getMessages({})
[
{ premium: false, sender: 'waverlymaven.testnet', text: 'TGIF' },
{
premium: true,
sender: 'waverlymaven.testnet',
text: 'Hello from New York ๐ŸŒˆ'
},
{ premium: false, sender: 'fhr.testnet', text: 'Hi' },
{ premium: true, sender: 'eugenethedream', text: 'test' },
{ premium: false, sender: 'dongri.testnet', text: 'test' },
{ premium: false, sender: 'dongri.testnet', text: 'hello' },
{ premium: true, sender: 'dongri.testnet', text: 'hey' },
{ premium: false, sender: 'hirokihori.testnet', text: 'hello' },
{ premium: true, sender: 'eugenethedream', text: 'hello' },
{ premium: false, sender: 'example-acct.testnet', text: 'Aloha' },
[length]: 10
]

Transactionsโ€‹

near tx-statusโ€‹

Queries transaction status by hash and accountId.

  • arguments: txHash --accountId
  • options: default

Example:

near tx-status FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK --accountId guest-book.testnet
Example Response

Transaction guest-book.testnet:FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK
{
status: { SuccessValue: '' },
transaction: {
signer_id: 'example-acct.testnet',
public_key: 'ed25519:AXZZKnp6ZcWXyRNdy8FztYrniKf1qt6YZw6mCCReXrDB',
nonce: 20,
receiver_id: 'guest-book.testnet',
actions: [
{
FunctionCall: {
method_name: 'addMessage',
args: 'eyJ0ZXh0IjoiQWxvaGEifQ==',
gas: 300000000000000,
deposit: '0'
}
},
[length]: 1
],
signature: 'ed25519:5S6nZXPU72nzgAsTQLmAFfdVSykdKHWhtPMb5U7duacfPdUjrj8ipJxuRiWkZ4yDodvDNt92wcHLJxGLsyNEsZNB',
hash: 'FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK'
},
transaction_outcome: {
proof: [ [length]: 0 ],
block_hash: '6nsjvzt6C52SSuJ8UvfaXTsdrUwcx8JtHfnUj8XjdKy1',
id: 'FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK',
outcome: {
logs: [ [length]: 0 ],
receipt_ids: [ '7n6wjMgpoBTp22ScLHxeMLzcCvN8Vf5FUuC9PMmCX6yU', [length]: 1 ],
gas_burnt: 2427979134284,
tokens_burnt: '242797913428400000000',
executor_id: 'example-acct.testnet',
status: {
SuccessReceiptId: '7n6wjMgpoBTp22ScLHxeMLzcCvN8Vf5FUuC9PMmCX6yU'
}
}
},
receipts_outcome: [
{
proof: [ [length]: 0 ],
block_hash: 'At6QMrBuFQYgEPAh6fuRBmrTAe9hXTY1NzAB5VxTH1J2',
id: '7n6wjMgpoBTp22ScLHxeMLzcCvN8Vf5FUuC9PMmCX6yU',
outcome: {
logs: [ [length]: 0 ],
receipt_ids: [ 'FUttfoM2odAhKNQrJ8F4tiBpQJPYu66NzFbxRKii294e', [length]: 1 ],
gas_burnt: 3559403233496,
tokens_burnt: '355940323349600000000',
executor_id: 'guest-book.testnet',
status: { SuccessValue: '' }
}
},
{
proof: [ [length]: 0 ],
block_hash: 'J7KjpMPzAqE7iX82FAQT3qERDs6UR1EAqBLPJXBzoLCk',
id: 'FUttfoM2odAhKNQrJ8F4tiBpQJPYu66NzFbxRKii294e',
outcome: {
logs: [ [length]: 0 ],
receipt_ids: [ [length]: 0 ],
gas_burnt: 0,
tokens_burnt: '0',
executor_id: 'example-acct.testnet',
status: { SuccessValue: '' }
}
},
[length]: 2
]
}


Global Optionsโ€‹

OptionDescription
--helpShow help [boolean]
--versionShow version number [boolean]
-v, --verbosePrints out verbose output [boolean] [default: false]