This project will no longer receive any updates.
We strongly recommend everyone to migrate to [pex-cli-rs
]instead.
PEX CLI is a Node.js application that relies on [pex-api-js
] to connect to and interact with the PEX blockchain. Create accounts, access keys, sign & send transactions with this versatile command line interface tool.
Note: Node.js version 16+ is required to run PEX CLI.
This release is a major reorganization of the codebase to simplify its maintenance. It also includes a few new features and a multitude of small fixes.
The most notable changes are:
-
Ledger users, please notice that the
--useLedger
does not set the path anymore, use--ledgerPath
for this- Please check the commands that support Ledger for more details
- Users can now import credentials using the
add-credentials
command - The
generate-key
command now has a--saveImplicit
option to save the key as an implicit account - Users can create
testnet
pre-funded accounts using the--useFaucet
option - Accounts cannot create
TLA
with less than 32 characters anymore (this is a PEX protocol change) - Removed unnecessary options from commands, e.g.
view
now does not take an--accountId
or--masterAccount
- If a command does not work, please first check the commands help to see if the options have changed
- For example, run
pex create-account
to see how options might have changed
- For example, run
Release notes and unreleased changes can be found in the CHANGELOG
Click on a command for more information and examples.
Command | Description |
---|---|
ACCESS KEYS | |
pex add-credentials |
Stores credentials for an account locally |
pex add-key |
adds a new access key to an account |
pex delete-key |
deletes an access key from an account |
pex generate-key |
generates a key pair and optionally stores it locally as credentials for an accountId |
pex list-keys |
displays all access keys and their details for a given account |
pex login |
stores a full access key locally using [PEX Wallet] |
ACCOUNTS | |
pex create-account |
creates a new account, either using a faucet to fund it, or an account saved locally |
pex delete-account |
deletes an account and transfers remaining balance to a beneficiary account |
pex list-keys |
displays all access keys for a given account |
pex send-pex |
sends tokens from one account to another |
pex state |
shows general details of an account |
CONTRACTS | |
pex call |
makes a contract call which can invoke change or view methods |
pex deploy |
deploys a smart contract to the PEX blockchain |
pex storage |
Shows the storage state of a given contract, i.e. the data stored in a contract |
pex view |
makes a contract call which can only invoke a view method |
TRANSACTIONS | |
pex tx-status |
queries a transaction's status by txHash
|
Make sure you have a current version of
npm
andNodeJS
installed.
- 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
pex-cli
globally by running:
npm install -g pex-cli
For example, on Ubuntu 20.04 pex-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 pex-cli
npm install -g pex-cli
# pex-cli works!
pex --help
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 installpex-cli
globally by running:
npm install -g pex-cli
The default network for
pex-cli
ismainnet
.
- You can change the network by prepending an environment variable to your command.
PEX_NETWORK=testnet pex send ...
- Alternatively, you can set up a global environment variable by running:
export PEX_NETWORK=mainnet
- All commands that interact with the network also allow to pass the
--networkId
option.
pex send-pex ... --networkId mainnet
[!WARNING] In previous versions,
pex-cli
usedPEX_ENV
to set the network. This can still be used, butPEX_NETWORK
has priority overPEX_ENV
if both are set.
You can set custom RPC server URL by setting this env variables:
PEX_MAINNET_RPC
PEX_TESTNET_RPC
Clear them in case you want to get back to the default RPC server.
Example:
export PEX_TESTNET_RPC=https://rpc.testnet.pex.org
All keys are stored locally at the root of your HOME
directory:
-
~/.pex-credentials
(MAC / Linux) -
C:\Users\YOUR_ACCOUNT\.pex-credentials
(Windows)
Inside .pex-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
Stores credentials (full-access-key) locally for an already existing account.
- arguments:
accountId
- options:
--seedPhrase
or--secretKey
Examples:
pex add-credentials example-acct.testnet --seedPhrase "antique attitude say evolve ring arrive hollow auto wide bronze usual unfold"
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. ([pex login
])
- arguments:
accountId
publicKey
Example:
pex 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.pexblocks.io/txns/EwU1ooEvkR42HvGoJHu5ou3xLYT3JcgQwFV3fAwevGJg
- 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:
pex 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.pexblocks.io/txns/H2BQL9fXVmdTbwkXcMFfZ7qhZqC8fFhsA8KDHFdT9q2r
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. ([pex login
])
Example:
pex 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.pexblocks.io/txns/4PwW7vjzTCno7W433nu4ieA6FvsAjp7zNFwicNLKjQFT
Displays a key-pair and seed-phrase and optionally stores it locally in
.pex-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.
Creates and displays a key pair
pex 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
Creates and displays a key pair, saving it locally in
.pex-credentials
as an implicit account.
pex 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 '~/.pex-credentials/testnet/9d6e4506ac06ab66a25f6720e400ae26bad40ecbe07d49935e83c7bdba5034fa.json'
Creates a key pair locally in
.pex-credentials
with anaccountId
that you specify.
Note: This does NOT create an account with this name.
pex 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 '~/.pex-credentials/testnet/example.testnet.json'
Uses a seed phrase to display a public key and implicit account
pex 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
Will store the key pair corresponding to the seedPhrase in .pex-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
Uses a connected Ledger device to display a public key and implicit account using the default HD path (
"44'/397'/0'/0'/1'"
)
pex 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 PEX 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
Uses a connected Ledger device to display a public key and implicit account using a custom HD path.
pex 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 PEX 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
Displays all access keys for a given account.
- arguments:
accountId
Example:
pex 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
]
locally stores a full access key of an account you created with MyPEXWallet.
- arguments:
none
- options:
--networkId
Example:
pex login
Custom wallet url:
Default wallet url is https://testnet.mypexwallet.com/
. But if you want to change to a different wallet url, you can setup the environmental variable PEX_MAINNET_WALLET
or PEX_TESTNET_WALLET
.
export PEX_TESTNET_WALLET=https://wallet.testnet.pex.org/
pex login
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
,--seedPhrase
,--publicKey
,--signWithLedger
,--ledgerPath
,--useLedgerPK
,--PkLedgerPath
Examples::
# Creating account using `example-acct.testnet` to fund it
pex create-account new-acc.testnet --useAccount example-acct.testnet
# Creating account using the faucet to fund it
pex create-account new-acc.testnet --useFaucet
# Creating a pre-funded account that can be controlled by the Ledger's public key
pex create-account new-acc.testnet --useFaucet --useLedgerPK
# Creating an account using a Ledger account
pex create-account new-acc.testnet --useAccount ledger-acct.testnet --signWithLedger
Subaccount example:
# Using an account to create a sub-account
pex create-account sub-acct.example-acct.testnet --useAccount example-acct.testnet
# Creating a sub-account using the Ledger that can also be controlled by the ledger
pex create-account sub.acc.testnet --useAccount sub.acc.testnet --signWithLedger --useLedgerPK
Example using --initialBalance
:
pex create-account sub-acct2.example-acct.testnet --useAccount example-acct.testnet --initialBalance 10
Example Response
Saving key to '/HOME_DIR/.pex-credentials/default/sub-acct2.example-acct.testnet.json'
Account sub-acct2.example-acct.testnet for network "default" was created.
Deletes an account and transfers remaining balance to a beneficiary account.
- arguments:
accountId
beneficiaryId
- options:
force
,--signWithLedger
,--ledgerPath
Example:
pex 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.pex.org, helper: https://helper.testnet.pex.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.pexblocks.io/txns/4x8xohER1E3yxeYdXPfG8GvXin1ShiaroqE5GdCd5YxX
Account sub-acct2.example-acct.testnet for network "default" was deleted.
Sends PEX tokens (Ⓝ) from one account to another.
- arguments:
senderId
receiverId
amount
- options:
--signWithLedger
,--ledgerPath
Note: You will need a full access key for the sending account. (pex login
)
Example:
pex send-pex sender.testnet receiver.testnet 10
Example Response
Sending 10 PEX 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.pexblocks.io/txns/BYTr6WNyaEy2ykAiQB9P5VvTyrJcFk6Yw95HPhXC6KfN
Shows details of an account's state.
- arguments:
accountId
Example:
pex 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"
}
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. (pex login
)
- arguments:
contractName
method_name
{ args }
--accountId
- options:
--gas
--deposit
--signWithLedger
--ledgerPath
Example:
pex 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.pexblocks.io/txns/FY8hBam2iyQfdHkdR1dp6w5XEPJzJSosX1wUeVPyUvVK
''
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. (pex login
)
Example:
pex deploy example-contract.testnet out/example.wasm
Initialize Example:
pex deploy example-contract.testnet 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.pex.org, helper: https://helper.testnet.pex.org, file: main.wasm
Transaction Id G8GhhPuujMHTRnwursPXE1Lv5iUZ8WUecwiST1PcKWMt
To see the transaction in the transaction explorer, please open this url in your browser
https://testnet.pexblocks.io/txns/G8GhhPuujMHTRnwursPXE1Lv5iUZ8WUecwiST1PcKWMt
Done deploying to example-contract.testnet
Shows the storage state of a given contract, i.e. the data stored in a contract.
- arguments:
contractName
- options:
--finality
,--utf8
,--blockId
,--prefix
Example:
pex storage hello.pex-examples.testnet --finality optimistic --utf8
Example Response
[ { key: 'STATE', value: '\x10\x00\x00\x00Passei por aqui!' } ]
Makes a contract call which can only view state. (Call is free of charge)
- arguments:
contractName
method_name
{ args }
- options:
default
Example:
pex 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
]
Queries transaction status by hash and accountId.
- arguments:
txHash
--accountId
- options:
default
Example:
pex 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
]
}
Option | Description |
---|---|
--help |
Show help [boolean] |
--version |
Show version number [boolean] |
-v, --verbose |
Prints out verbose output [boolean] [default: false] |
Got a question? Ask it on StackOverflow!
This repository is distributed under the terms of both the MIT license and the Apache License (Version 2.0). See LICENSE and LICENSE-APACHE for details.