The matrix CLI
matrix drives a running node: health, providers, jobs, balances, inference, and a local wallet that signs transfers so the node never sees a private key.
Build it
# from services/core
go build -o matrix ./cmd/matrix
go install ./cmd/matrix # or put it on your PATH
matrix --help # the full command treeOr take a prebuilt binary from a release.
Global flags
--addr(default127.0.0.1:9091) - the market gRPC endpoint. Almost every command talks to this one.--inference-addr(default127.0.0.1:9092) - the inference gRPC endpoint. It is a separate server on a separate port, so pointing--addrat a remote node is not enough formatrix inference; it is a flag on theinferencecommands only.--api-key- sent as theauthorizationgRPC metadata header. Required on a node withsecurity.enable_aclson, which is the default a generated config writes.--timeout(default10s) and--jsonfor machine-readable output.
The whole loop in one command
matrix --api-key <key> quickstart
# wallet -> funded buyer -> registered provider -> job -> settlement, in one command
# --provider --capacity --price --units --fund --wallet all override the defaultsNode and providers
matrix status # endpoint + serving status
matrix health # the gRPC health Check: SERVING / NOT_SERVING
matrix provider register --id gpu-1 --capacity 100 --price 5
matrix provider list # local providers
matrix provider list --include-remote # plus providers discovered over p2pprovider list on a freshly initialized node already has one entry - the GPU-free echo provider the node registers so the inference path works before you have a model server:
ID CAPACITY AVAILABLE PRICE/UNIT ORIGIN PEER
demo-inference-provider 100 100 5 local
quickstart-provider 100 90 5 localJobs and balances
matrix job submit --buyer <account-id> --provider gpu-1 --units 10
matrix job complete --id <job-id> # settles: moves native MATRIX buyer -> provider
matrix job cancel --id <job-id> # releases the reserved capacity, charges nothing
matrix balance --account <account-id>
matrix fund --account <account-id> --amount 1000000 # from the genesis reward poolfund moves native MATRIX out of the genesis reward pool; it never mints, so the billion-MATRIX cap holds however often you call it.
job complete settles through consensus: the payment is a transfer signed by the buyer that a quorum commits and every node applies. The node therefore needs the buyer's signing key, which it resolves from the wallet files under ~/.matrix. A job whose buyer it holds no key for is refused with FailedPrecondition and the reservation left intact, so you can cancel it. That refusal is the point: paying out of an account without its owner's signature is what this path exists to stop.
Wallet
An ed25519 keypair at ~/.matrix/wallet.json, mode 0600. The private key is never printed or logged: a transfer is signed locally and only the public key, the signature and the transfer fields go to the node.
matrix wallet create # refuses to overwrite an existing file
matrix wallet show # the account id (which is the public key)
matrix wallet balance
matrix wallet transfer --to <recipient-account-id> --amount 200
# every wallet command takes --wallet to use a file other than ~/.matrix/wallet.jsonInference
matrix inference submit \
--buyer <account-id> \
--provider demo-inference-provider \
--model demo \
--prompt "one sentence about peer-to-peer compute"
matrix inference get --id <job-id>
# --fulfill defaults to true: the job is reserved, run and settled in one call.
# --fulfill=false reserves only.What a run against the demo provider prints:
id: 13ac1c62-5013-4c31-8cbd-c5f3b7848d23
buyer: c5b097824f2e2222a278af3dbe4b519fa653a96e44ff08891668b3a2a708d5d9
provider: demo-inference-provider
model: demo
status: completed
units: 5
completion: echo: user: one sentence about peer-to-peer computeAn inference job is a compute job with a prompt attached: it reserves capacity from a registered provider, runs on that provider's backend, and settles at that provider's price through consensus - which means the node needs the buyer's signing key. It resolves one from the wallet files under ~/.matrix, so the wallet you created above works and an arbitrary account id does not.
Transactions
matrix tx list --limit 20 # ascending commit order
matrix tx list --start 10 --limit 20
matrix tx get --index 3What tx list shows
These read the consensus transaction history: the ordered sequence of value transfers that committed blocks carried. A wallet transfer, SubmitSignedTransfer, and the buyer-to-provider payment behind a compute or inference settlement all settle through consensus, so they all appear here in commit order. Because the history comes from the committed block chain, two nodes list the same transfers in the same order. Reserved consensus operations (bonds, withdrawals, validator set changes) are protocol state, not transfers, so they are omitted.
Next
- Quickstart - a node and a settled job in about a minute
- Configuration - every field, including where the API key lives
- The CLI's own README