> ## Documentation Index > Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt > Use this file to discover all available pages before exploring further. # peaqOS CLI > Drive activate, qualify, scale, and operator flows from your terminal. export const KeyTerms = ({all = {}, ids = [], title = "Key terms in this guide"}) =>
{title}
{ids.map(id => { const t = all[id] || ({}); return
{t.term}. {t.def}
; })}
; export const G = { onchain: { id: "onchain", cat: "chain-infra", term: "On-chain vs off-chain", def: "On-chain means written to the shared public ledger every machine agrees on: permanent and readable by anyone. Off-chain means kept on a normal private server instead." }, blockchain: { id: "blockchain", cat: "chain-infra", term: "Chain / blockchain", def: "A shared, tamper-resistant public database maintained by a whole network of computers with no single owner. Different chains are separate such networks." }, peaqChain: { id: "peaqChain", cat: "chain-infra", term: "peaq chain", def: "The machine-focused blockchain peaqOS uses as home base for identity and credit records." }, transaction: { id: "transaction", cat: "chain-infra", term: "Transaction (tx) / tx hash", def: "A single signed request that changes the ledger. Its hash is a unique, receipt-like ID you can use to look it up later." }, rpcUrl: { id: "rpcUrl", cat: "chain-infra", term: "RPC URL / endpoint", def: "The network address your code calls to read from or write to a chain, like the base URL of the chain's API server." }, mainnet: { id: "mainnet", cat: "chain-infra", term: "Mainnet / testnet (agung)", def: "Mainnet is the real, live network where tokens have real value. Testnet is a free practice copy with worthless tokens; peaq's is called agung." }, evm: { id: "evm", cat: "chain-infra", term: "EVM / EVM-compatible", def: "The Ethereum Virtual Machine: the standard runtime many chains share, so the same 0x... addresses and tools work across all of them. peaq is EVM-compatible." }, node: { id: "node", cat: "chain-infra", term: "Node (RPC node)", def: "A server running the blockchain software that holds a copy of the ledger and answers queries. NOT a ROS 2 node, despite the shared word." }, chainId: { id: "chainId", cat: "chain-infra", term: "Chain ID", def: "A number that uniquely labels a chain so software doesn't confuse networks (peaq is 3338, Base is 8453)." }, precompile: { id: "precompile", cat: "chain-infra", term: "Precompile", def: "A built-in function baked into the chain at a fixed address that acts like a contract but runs as faster native code. The batch one bundles several actions into one all-or-nothing transaction." }, dataHash: { id: "dataHash", cat: "chain-infra", term: "Data hash (keccak256)", def: "A short, fixed-length fingerprint of a file, stored on-chain instead of the file itself, so data can be verified later while the raw data stays off-chain." }, wallet: { id: "wallet", cat: "wallet-keys", term: "Wallet", def: "An account on the chain, identified by a public address, that holds a machine's funds and approves its actions. Really just a pair of keys, not a place money is stored." }, keypair: { id: "keypair", cat: "wallet-keys", term: "Keypair", def: "The two matched secrets behind a wallet: a public address you can share, and a private key you keep secret that signs actions." }, privateKey: { id: "privateKey", cat: "wallet-keys", term: "Private key", def: "The secret string that proves you control a wallet. Anyone who has it has full control, like a master password that can never be reset." }, sign: { id: "sign", cat: "wallet-keys", term: "Sign / signature", def: "Using your private key to produce a cryptographic stamp proving you approved a specific action, without ever revealing the key." }, signer: { id: "signer", cat: "wallet-keys", term: "Signer / signing identity", def: "The wallet whose private key authorizes an action: the account the network treats as the one taking it. NOT a file or an app." }, address: { id: "address", cat: "wallet-keys", term: "Address (0x...)", def: "The public 0x... identifier of a wallet or contract you can freely share so others can send to it or look it up, like an account number." }, eoa: { id: "eoa", cat: "wallet-keys", term: "EOA (externally owned account)", def: "A plain wallet controlled directly by a private key, as opposed to one controlled by code. Here, the account that IS the machine." }, ows: { id: "ows", cat: "wallet-keys", term: "OWS / wallet vault", def: "An open standard for storing wallet keys in an encrypted local file (a vault) with a backup phrase and an activity log, instead of a bare key in a text file." }, passphrase: { id: "passphrase", cat: "wallet-keys", term: "Passphrase (OWS_PASSPHRASE)", def: "The password that unlocks the encrypted wallet vault so its key can be used to sign." }, mnemonic: { id: "mnemonic", cat: "wallet-keys", term: "Mnemonic / seed phrase", def: "A list of 12 or 24 ordinary words that encodes a wallet's secret key, used to back it up and recover it. Whoever has the words controls the wallet." }, derivation: { id: "derivation", cat: "wallet-keys", term: "Derivation path", def: "The deterministic recipe that turns one backup phrase into many specific keys and addresses, one per network or index." }, challenge: { id: "challenge", cat: "wallet-keys", term: "Challenge (sign-to-prove)", def: "A login-style handshake: the server sends a random message, you sign it with your key, and the signature proves you control the account without sending the key." }, eip191: { id: "eip191", cat: "wallet-keys", term: "EIP-191 / personal_sign", def: "A standard way to sign a plain message to prove you control an account, without sending any on-chain transaction." }, did: { id: "did", cat: "identity", term: "DID / peaqID", def: "A globally unique, self-owned ID for a machine that lives on the chain and isn't issued by any single company. peaqID is peaq's version, written did:peaq:0x..." }, register: { id: "register", cat: "identity", term: "Register a machine", def: "Putting a machine on the network for the first time, which gives it an ID, a DID, an ownership token, and a locked deposit. registerMachine is self-managed; registerFor is on someone else's behalf." }, machineId: { id: "machineId", cat: "identity", term: "Machine ID", def: "The number the network assigns your machine when it registers, used as its handle in every later call." }, ownerOperator: { id: "ownerOperator", cat: "identity", term: "Owner / operator", def: "The owner owns a machine; the operator runs it. They can be the same account (self-managed) or different (proxy-managed)." }, proxyOperator: { id: "proxyOperator", cat: "identity", term: "Proxy operator", def: "One account that registers and manages many machines on behalf of their owners, so a fleet operator can handle a whole fleet from one wallet." }, didAttributes: { id: "didAttributes", cat: "identity", term: "DID attributes", def: "Public name-value facts (a docs link, a data endpoint) attached to a machine's DID and stored on-chain for anyone to read. Writing them is a separate transaction from registration." }, pairing: { id: "pairing", cat: "identity", term: "Pairing / pairing token", def: "The verified link between an AI agent and a machine, set up by signing a challenge. The pairing token is the signed credential the agent sends with each request, like a temporary access badge." }, hardwareAttestation: { id: "hardwareAttestation", cat: "identity", term: "Hardware attestation", def: "A tamper-resistant chip on the machine cryptographically vouching that it's genuine hardware, so its identity can't be faked in software. This is the Verify layer." }, gas: { id: "gas", cat: "tokens-economics", term: "Gas", def: "The small fee, paid in the chain's token, that every action writing to the ledger costs, like a per-write transaction cost." }, peaqToken: { id: "peaqToken", cat: "tokens-economics", term: "PEAQ (token)", def: "The peaq network's own token, used to pay gas fees and to lock up as the deposit when registering a machine." }, gasStation: { id: "gasStation", cat: "tokens-economics", term: "Gas Station / faucet", def: "A peaq service that hands a brand-new, empty wallet a tiny starting amount of tokens so it can afford its first network fees. Gated by 2FA." }, bond: { id: "bond", cat: "tokens-economics", term: "Bond", def: "A refundable deposit (currently 1 PEAQ) you lock up to register a machine, proving skin in the game, like a security deposit. Bonded means the deposit is in place." }, nft: { id: "nft", cat: "tokens-economics", term: "NFT", def: "A unique, one-of-a-kind ownership token recorded on the chain. Unlike a coin, no two are interchangeable." }, mint: { id: "mint", cat: "tokens-economics", term: "Mint / minting", def: "Creating a brand-new token on the chain and assigning it to an owner, like stamping a fresh serial-numbered certificate into existence." }, machineNft: { id: "machineNft", cat: "tokens-economics", term: "Machine NFT", def: "The unique token representing one specific physical machine and its financial profile. It can be sold or bridged on its own, separate from the machine's identity." }, identityNft: { id: "identityNft", cat: "tokens-economics", term: "Identity NFT", def: "A non-transferable (soulbound) token minted automatically when a machine registers, representing its identity. Its token ID equals the machine ID." }, tokenId: { id: "tokenId", cat: "tokens-economics", term: "Token ID", def: "The unique number identifying one specific token within a collection, like a serial number." }, mcr: { id: "mcr", cat: "tokens-economics", term: "Machine Credit Rating (MCR)", def: "A creditworthiness score for a machine (a Moody's-style grade AAA down to NR, plus a 0-100 number) computed from its recorded earnings and activity. Like a credit score for a robot." }, mcrApi: { id: "mcrApi", cat: "tokens-economics", term: "MCR API", def: "The public web service you call to fetch a machine's credit score and profile as JSON, and the one place a machine's monetization is switched on or off with a signed message. No login needed: reads are open, and the write is authorized by the signature itself." }, provisioned: { id: "provisioned", cat: "tokens-economics", term: "Provisioned / NR (Not Rated)", def: "Early MCR statuses. Provisioned means registered and bonded but with too little history to score yet. NR means no grade, because the score is too low or the machine isn't bonded." }, event: { id: "event", cat: "tokens-economics", term: "Event (revenue / activity)", def: "A recorded data point about a machine's work, submitted to the chain to feed its credit score. Revenue events report money earned; activity events report work with no money. NOT a ROS topic message." }, trustLevel: { id: "trustLevel", cat: "tokens-economics", term: "Trust level", def: "A label on each submitted event saying how strongly its truth is backed: the machine's word (0), a checkable on-chain record (1), or tamper-proof hardware proof (2)." }, escrow: { id: "escrow", cat: "tokens-economics", term: "Escrow", def: "Holding a buyer's payment in a neutral locked place until the service is delivered, then releasing it, so neither side has to trust the other first." }, paymentRail: { id: "paymentRail", cat: "tokens-economics", term: "Payment rail", def: "The specific method or channel a payment moves through, like choosing card vs bank transfer vs a particular token." }, x402: { id: "x402", cat: "tokens-economics", term: "x402", def: "A web payment standard where a server answers 'payment required' with exact instructions, and the buyer's wallet signs an authorization instead of sending a separate transaction — built for machines and agents paying per request." }, usdt: { id: "usdt", cat: "tokens-economics", term: "USDT", def: "A stablecoin token meant to hold a value of one US dollar, used to pay service providers without price swings." }, fractionalize: { id: "fractionalize", cat: "tokens-economics", term: "Fractionalize (ERC-3643)", def: "Splitting ownership of one machine into many small tradable shares so multiple people can each own a piece. ERC-3643 is the regulated-securities token standard used to do it." }, smartContract: { id: "smartContract", cat: "smart-contracts", term: "Smart contract / contract address", def: "A program deployed on the chain that runs exactly as written and that anyone can call, identified by its own 0x... address." }, registryContracts: { id: "registryContracts", cat: "smart-contracts", term: "Registry contracts", def: "On-chain programs that each keep an official, lookup-able list: IdentityRegistry tracks which machines exist, EventRegistry stores their events, IdentityStaking holds their deposits." }, smartAccount: { id: "smartAccount", cat: "smart-contracts", term: "Smart account (ERC-4337)", def: "A programmable wallet controlled by code instead of a single key, so it can enforce rules like spending limits. Each machine gets one at activation." }, submitEvent: { id: "submitEvent", cat: "smart-contracts", term: "submitEvent / batchSubmitEvents", def: "The calls that record one or many of a machine's revenue or activity entries onto the chain." }, revert: { id: "revert", cat: "smart-contracts", term: "Revert", def: "When an on-chain call is rejected and fully undone because a rule was broken, leaving no changes and usually a named error." }, soulbound: { id: "soulbound", cat: "smart-contracts", term: "Soulbound", def: "A token that can never be transferred or sold and stays permanently attached to one owner. The Identity NFT is soulbound." }, bridge: { id: "bridge", cat: "cross-chain", term: "Bridge / bridging", def: "Moving a token from one chain to another, so the same Machine NFT can exist on a different chain. peaq and Base are live today; bridging is mainnet-only." }, base: { id: "base", cat: "cross-chain", term: "Base", def: "Another blockchain network (built by Coinbase) that peaqOS can move Machine NFTs to and from. Paying fees on Base needs Base ETH." }, omniChain: { id: "omniChain", cat: "cross-chain", term: "Omni-chain / cross-chain", def: "Working across many separate chains at once, so a machine's identity and credit created on peaq can be read or used on other chains." }, homeChain: { id: "homeChain", cat: "cross-chain", term: "Home chain", def: "The chain where a record's canonical, authoritative copy lives. For peaqOS that is peaq chain; every other chain holds a mirror." }, satelliteChain: { id: "satelliteChain", cat: "cross-chain", term: "Satellite chain", def: "A chain carrying a read-only, automatically synced mirror of home-chain records, so apps there can use them without crossing back to the home chain." }, sourceChainId: { id: "sourceChainId", cat: "cross-chain", term: "sourceChainId / sourceTxHash", def: "Two fields recording which chain an action happened on and its hash there, so a cross-chain event can be traced back and verified." }, machineAgent: { id: "machineAgent", cat: "general-web3", term: "Machine Agent", def: "A third-party AI program (Claude, OpenAI, a custom bot) paired to a machine and given limited permission to find, buy, and pay for services on its behalf." }, delegationPolicy: { id: "delegationPolicy", cat: "general-web3", term: "Delegation policy", def: "The rules an owner gives an AI agent that cap how much it can spend per transaction and per day and which services it may use, so it transacts within guardrails." }, machineMarkets: { id: "machineMarkets", cat: "general-web3", term: "Machine Markets / Service Registry", def: "peaqOS's marketplace where machines list services they offer (Service Registry) and where agents discover, order, pay for, and run services from others." }, sdk: { id: "sdk", cat: "general-web3", term: "SDK (peaq-os-sdk)", def: "peaq's code library (Python and JS) you install to call all this functionality without writing low-level blockchain calls yourself." }, stream: { id: "stream", cat: "data-stream", term: "Stream (Data-as-a-Service)", def: "The peaqOS function where a machine sells the data it generates: it signs the data, encrypts what's sensitive, and grants buyers access. Selling data, as opposed to selling capacity (that's Monetize)." }, edgeAgent: { id: "edgeAgent", cat: "data-stream", term: "peaqOS Edge Agent", def: "Software that runs on the machine itself (as a ROS 2 node) and signs, encrypts, and ships the data it produces. The on-machine half of Stream." }, dataPackage: { id: "dataPackage", cat: "data-stream", term: "Signed data package", def: "A bundle of machine data stamped with the machine's identity (DID, timestamp, sequence number) and a signature, so anyone can prove which machine produced it and that it wasn't altered." }, dataEventMap: { id: "dataEventMap", cat: "data-stream", term: "Data Event Map", def: "The policy file a machine owner writes to control what streams out: which topics to read, which fields to keep, drop, or encrypt, and where the signed data goes." }, chunk: { id: "chunk", cat: "data-stream", term: "Chunk", def: "A bounded, individually encrypted slice of a data stream (by time window or size). The unit a buyer actually purchases and decrypts." }, chunkChain: { id: "chunkChain", cat: "data-stream", term: "Chunk chain", def: "A run of chunks linked in order, each referencing the one before it, so missing, reordered, or edited chunks are detectable. Tamper-evidence for a continuous stream." }, manifest: { id: "manifest", cat: "data-stream", term: "Manifest", def: "A signed record describing a chunk or dataset — its hashes, storage location, and encryption details — without the data itself. Buyers verify the manifest before trusting or buying." }, dataset: { id: "dataset", cat: "data-stream", term: "Dataset", def: "A group of chunks for one topic and time range, packaged for sale with a single fingerprint (a Merkle root) that covers every chunk in it." }, merkleRoot: { id: "merkleRoot", cat: "data-stream", term: "Merkle root", def: "One short hash that stands in for a whole set of items, letting you later prove a specific chunk belongs to a dataset without revealing the rest." }, envelopeEncryption: { id: "envelopeEncryption", cat: "data-stream", term: "Envelope encryption / key wrapping", def: "Encrypt the data once with a random key, then lock that key separately for each authorized reader. Granting a buyer access re-locks the key to their public key — the data itself is never re-encrypted." }, accessGrant: { id: "accessGrant", cat: "data-stream", term: "Access grant", def: "What a buyer receives after paying: the chunk keys they bought, each locked to their public key. They unlock with their private key and decrypt only those chunks." }, contextProvider: { id: "contextProvider", cat: "data-stream", term: "Context Provider", def: "A third party that buys machine data, normalizes it into datasets, and serves or resells it (for example, for AI training). The buyer side of Stream, such as DataHive." }, computeProvider: { id: "computeProvider", cat: "monetize", term: "Compute provider", def: "A machine that rents out its processing power to a compute network. Instead of sitting idle, the machine runs other people's workloads and earns for it." }, provisioningManifest: { id: "provisioningManifest", cat: "monetize", term: "Provisioning manifest", def: "A published, step-by-step install plan that turns a machine into a compute provider: the checks to run first, the commands to execute, and the probes that prove it worked. The machine pulls it on demand and runs it locally." }, heartbeat: { id: "heartbeat", cat: "monetize", term: "Heartbeat", def: "A short signed 'I'm here' message a machine sends out at a regular interval. As long as heartbeats keep arriving, the machine counts as online; if they stop, it's marked offline automatically." }, aggregator: { id: "aggregator", cat: "monetize", term: "Aggregator", def: "A network that pools capacity from many machines and sells it on, such as a decentralized compute marketplace. Machines connect to an aggregator, which then dispatches work to them." }, machineWallet: { id: "machineWallet", cat: "monetize", term: "Machine wallet", def: "The wallet that belongs to the machine itself, separate from its owner's or operator's wallet. Earnings from the machine's work land here by default." }, walrus: { id: "walrus", cat: "chain-infra", term: "Walrus", def: "A decentralized storage network where encrypted data chunks can be parked, referenced by walrus:// links. The data stays off the blockchain; only its reference and fingerprint are tracked on-chain." }, solana: { id: "solana", cat: "cross-chain", term: "Solana", def: "A high-throughput blockchain. peaqOS wallets can hold a Solana account and sign Solana transactions, and machine-economy payments can settle there." } }; The peaqOS CLI wraps the SDK into a terminal surface for the most common machine flows: registering a machine, submitting events, querying credit ratings, managing proxy-operator fleets, and the full Scale loop — pairing an AI agent, searching the Machine Markets catalogue, placing and confirming orders. It's the same on-chain and orchestration path as the [JS](/peaqos/sdk-reference/sdk-js) and [Python](/peaqos/sdk-reference/sdk-python) SDKs, scripted. ## Install ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} pip install peaq-os-cli peaqos --version ``` Python 3.10+ required. Ships to PyPI as `peaq-os-cli` and exposes the `peaqos` command. Wraps the [Python SDK](/peaqos/sdk-reference/sdk-python): same on-chain path, scripted. `peaqos --version` prints both the CLI and the underlying `peaq_os_sdk` versions on a single line. Global flags `-v` / `--verbose` and `-q` / `--quiet` toggle DEBUG and ERROR-only logging respectively (mutually exclusive; logs go to stderr). `--orchestration-url ` and `--orch-api-key ` are global overrides for the corresponding env vars on any `peaqos scale ...` invocation. ## Configure The CLI reads the same environment variables as the SDKs. Full table on [Install](/peaqos/install#environment-variables). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} export PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public export PEAQOS_PRIVATE_KEY=0x... # Defaults to http://127.0.0.1:8000 (self-hosted MCR). # Set to the public peaq MCR for mainnet reads. export PEAQOS_MCR_API_URL=https://mcr.peaq.xyz ``` Other RPC endpoints are available. See [Public RPC endpoints](/peaqos/install#public-rpc-endpoints). Or scaffold a `.env` interactively with `peaqos init`. ## Commands ### `peaqos init` Interactive wizard that scaffolds a `.env` with the required peaqOS variables. Prompts for network, private key source (`paste`, `generate`, or `wallet`), RPC URL, MCR API URL, Gas Station URL, Event Registry address, and (optionally) `PEAQOS_ORCHESTRATION_URL` + `PEAQOS_ORCH_API_KEY` for Machine Markets. The orchestration key is masked in any echoed or logged output. The `wallet` path creates a new OWS vault wallet and writes `PEAQOS_OWS_WALLET=` instead of `PEAQOS_PRIVATE_KEY`. Writes `.env` with `0o600` permissions and auto-runs `whoami` to verify. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos init peaqos init --force # overwrite existing .env without prompt peaqos init --non-interactive # read all values from env vars ``` ### `peaqos whoami` Read-only command that prints the signing address, network, chain ID, RPC + MCR API URLs, and all peaqOS contract addresses the CLI is configured with. Useful as a sanity check after `init`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos whoami ``` ### `peaqos activate` Register a machine on peaq end-to-end: balance check, Gas Station funding (when 2FA is configured), `register_machine`, mint the Machine NFT, write DID attributes. Idempotent: safe to re-run if a step fails. Mirrors the [Activate](/peaqos/functions/activate) flow. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Self-managed: caller's own key drives every step peaqos activate --doc-url "https://example.com/docs" --data-api "https://example.com/events" # Proxy-managed: caller activates on behalf of a machine EOA that signs its own DID writes peaqos activate --for 0xMachineAddress --machine-key ./machine.key --doc-url "https://example.com/docs" --data-api "https://example.com/events" ``` #### Flags | Flag | Required | Meaning | | :--------------- | :------- | :------------------------------------------------------------------------------ | | `--for` | no | Machine EOA address. Presence switches to proxy mode; requires `--machine-key`. | | `--machine-key` | no | Path to a file containing the machine's `0x`-prefixed hex private key. | | `--doc-url` | yes | Documentation URL written to the machine DID. | | `--data-api` | yes | Raw data API URL written to the machine DID. | | `--visibility` | no | Data visibility: `public` (default), `private`, or `onchain`. | | `--skip-funding` | no | Skip steps 1–3 (balance check, 2FA enrollment, Gas Station funding). | Private keys must be supplied via file path (`--machine-key`). Inline key flags are intentionally unsupported: reading from a file keeps the key out of shell history and `ps` output. **Proxy preconditions.** Proxy mode requires the operator to already be registered on `IdentityRegistry` (i.e. have run `peaqos activate` in self mode first). If not, the command exits `2` before spending any gas. #### Output streams The final summary (`Machine ID`, `Token ID`, `Machine DID`; plus `Machine Address` and `Operator DID` in proxy mode) goes to **stdout** so it can be piped or captured. Progress lines (`[1/6]`, `[2/6]`, …) and per-step info/warning messages go to **stderr**. #### Idempotent rerun Every mutating step does a read-before-write precheck. Re-running `peaqos activate` against state that's already complete submits no transactions and exits `0`. A TOCTOU revert (`AlreadyRegistered` / `AlreadyExists`) is recovered as a skip rather than surfaced as a network error. #### `peaqos.log` Every step appends a JSONL entry to `./peaqos.log` (`0o600`) in the working directory: a resume marker for partial failures and the audit trail. ```jsonl theme={"theme":{"light":"github-light-default","dark":"github-dark"}} {"address":"0xDC5b...","machine_id":42,"mode":"self","status":"confirmed","step":"register","ts":"2026-04-23T15:00:18.482917+00:00"} {"machine_id":42,"recipient":"0xDC5b...","status":"confirmed","step":"mint_nft","token_id":11,"tx_hash":"0xminttx...","ts":"..."} {"machine_did_tx_count":6,"machine_id":42,"mode":"self","status":"confirmed","step":"machine_did","token_id":11,"tx_hash":"0xdidtx...","ts":"..."} ``` Keys are alphabetically sorted on disk (`json.dumps(..., sort_keys=True)`); `ts` is the UTC `datetime.isoformat()` (`+00:00` suffix, microseconds included) and sits where the alphabetic order puts it on each line (last for most rows). `status` is one of `pending` / `skipped` / `failed` / `confirmed`. On rerun, the same rows reappear as `"status":"skipped"` and, for DID writes, with `"recovered_from":"AttributeAlreadyOnChain"`. Fund-step retries with the same `request_id` carry `"resumed_from":"pending"` on the new `pending` row instead. ### `peaqos qualify event` Submit a revenue or activity event to the EventRegistry. Wraps [`submit_event`](/peaqos/sdk-reference/sdk-python#submit_event). See the [Submit events guide](/peaqos/guides/submit-events) for trust levels and cross-chain patterns. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # HK$1.23 (123 cents) revenue event peaqos qualify event \ --machine-id 42 \ --type revenue \ --value 123 \ --ts 2026-04-23T12:00:00Z \ --trust self \ --source-chain peaq ``` `--value` is an ISO 4217 minor-unit integer: cents for USD/HKD, whole units for JPY/KRW/VND. `HK$1.23 → --value 123`, `¥100 → --value 100`. The CLI defaults `--currency` to `USD` for revenue events and to `""` for activity events; pass `--currency` explicitly to override. The MCR API converts the value to USD using FX at the event timestamp. | Flag | Required | Meaning | | :--------------- | :---------- | :--------------------------------------------------------------------------------------------------------------- | | `--machine-id` | yes | Positive integer machine ID. | | `--type` | yes | `revenue` or `activity`. | | `--value` | yes | Non-negative integer in the currency's minor unit. | | `--ts` | yes | Unix seconds or ISO 8601 with timezone (`Z` or `+hh:mm`). Must be on or before block time. | | `--currency` | no | ISO 4217 code, 3-10 uppercase alphanumerics (`^[A-Z0-9]{3,10}$`). Default: `USD` for revenue, `""` for activity. | | `--trust` | no | `self` (default), `onchain`, or `hardware`. | | `--source-chain` | no | `same` (default), `peaq`, or `base`. | | `--source-tx` | conditional | 32-byte hex tx hash. **Required** when `--trust onchain`. | | `--raw-data` | no | Path to a file; bytes are hashed and stored as the event data hash. | | `--metadata` | no | Path to a file; bytes are attached as on-chain metadata. Absent = empty bytes. | Human output on success: ``` Event submitted. Machine ID: 42 Type: revenue Value: 123 Trust: self-reported Tx: 0x3f4a8c1e2d9b7f05a6c3e8d1f4b2a7c9e0d5f3b1a8e2c6d9f7b4a1e3c5d8f2b4 Data Hash: 0xa1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890 ``` ### `peaqos qualify mcr` Fetch a machine's credit rating from the [MCR API](/peaqos/api-reference/get-mcr). Wraps [`query_mcr`](/peaqos/sdk-reference/sdk-python#query_mcr). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos qualify mcr did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5 peaqos qualify mcr did:peaq:0x9a5F... --json ``` The DID must match `did:peaq:0x` plus 40 hex characters. `--json` emits the raw SDK response on stdout with no banner or prose: useful for `jq` and scripting. Human output: ``` MCR for did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5 Rating: A Score: 82 / 100 Bond Status: bonded Events: Total: 150 Revenue: 120 Activity: 30 30-Day Revenue: up Last Updated: 2026-04-20T14:30:00Z FX Degraded: no ``` `revenue_trend` is one of `up`, `stable`, `down`, or `insufficient` (returned when there isn't enough revenue history to compute a trend). `FX Degraded:` reflects the top-level `mcr_degraded` field — `yes` when one or more scored events used a stale or unavailable FX snapshot, `no` otherwise. `--json` output (raw SDK `MCRResponse`): ```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}} { "did": "did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5", "machine_id": 42, "mcr_score": 82, "mcr": "A", "mcr_degraded": false, "bond_status": "bonded", "negative_flag": false, "event_count": 150, "revenue_event_count": 120, "activity_event_count": 30, "revenue_trend": "up", "total_revenue": 1542075, "average_revenue_per_event": 12851, "last_updated": 1745152200 } ``` ### `peaqos show machine` Fetch a full machine profile: Machine ID, operator, DID attributes, MCR snapshot, recent events. Wraps [`query_machine`](/peaqos/sdk-reference/sdk-python#query_machine). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos show machine did:peaq:0xabc1230000000000000000000000000000000001 peaqos show machine did:peaq:0xabc... --json ``` ### `peaqos show operator machines` List the machines registered under a proxy operator, with MCR per machine. Wraps [`query_operator_machines`](/peaqos/sdk-reference/sdk-python#query_operator_machines). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos show operator machines did:peaq:0xProxyAddress peaqos show operator machines did:peaq:0xProxyAddress --json ``` ### `peaqos wallet` Manage OWS-format wallets in the local encrypted vault at `~/.ows/wallets/`. Requires the `[ows]` extra: `pip install 'peaq-os-cli[ows]'` (quote the bracketed extra so zsh does not glob it). The vault passphrase is read from `OWS_PASSPHRASE` when set, otherwise prompted interactively. Subcommands wrap the SDK static helpers documented on [Wallets (OWS)](/peaqos/wallets). | Subcommand | Purpose | | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `peaqos wallet create [--words 12\|24] [--json]` | Generate a new BIP-39 mnemonic and derive accounts for every supported chain. The mnemonic is not displayed; back up via `wallet export`. | | `peaqos wallet import --mnemonic [--index N] [--json]` | Import from an existing BIP-39 mnemonic (hidden prompt). `--index` selects the derivation index (default `0`). | | `peaqos wallet import --private-key-file [--json]` | Import a raw EVM private key from file. peaq-only; other chains synthesize on read where possible. | | `peaqos wallet list [--json]` | Compact table of all wallets: Name, ID, peaq Address, Key Type, Created. | | `peaqos wallet show [--json]` | Wallet metadata plus the full multi-chain address table. | | `peaqos wallet export ` | Reveal the recovery phrase / private key. Requires interactive confirmation. Secret prints to stdout; warning prints to stderr. | | `peaqos wallet delete ` | Securely delete a wallet (file overwritten with random bytes before unlink). Requires confirmation. | | `peaqos wallet use ` | Set the active wallet. Writes `PEAQOS_OWS_WALLET=` into `.env` in the current directory. Subsequent commands that call `load_client()` will sign with this wallet. | When `PEAQOS_OWS_WALLET` is set, `load_client()` resolves the wallet from the vault using `OWS_PASSPHRASE` and skips `PEAQOS_PRIVATE_KEY` entirely. If both are set, the wallet wins. ### `peaqos stream` The data-stream command group. The crypto core is offline: `publish` turns a source file into signed, encrypted chunks on disk; `grant` re-wraps the chunk keys for a buyer; `consume` decrypts and reassembles the original data on the buyer's side. Around it sits the paid flow, new in CLI `v0.0.6`: `distribute` waits for a buyer's payment confirmation and delivers access files to S3, `pay` transfers tokens to the seller on peaq, Base, or Solana, and `payproof` submits proof for a transfer completed elsewhere. Discovery and ordering happen through the [Stream data marketplace](/peaqos/api-reference/stream-marketplace); the SDK-level [P2P delivery channel](/peaqos/sdk-reference/stream-distribution#p2p-delivery) has no CLI flag yet. #### `peaqos stream publish` Chunk, encrypt, and sign a data file into a local output directory. Each chunk gets a fresh key wrapped (X25519) for three recipients — owner, operator, machine — and the chain is signed Ed25519. Writes `chunk-{i}.json` (envelope) + `chunk-{i}.bin` (ciphertext) per chunk, plus a `manifest.json` (`peaq.stream.chunks.v1`). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos stream publish \ --input ./telemetry.bin \ --output-dir ./out \ --owner-public-key 0x<64hex> \ --operator-public-key 0x<64hex> \ --machine-public-key 0x<64hex> \ --signing-key-file ./machine-ed25519.key \ --machine-did did:peaq:0xMACHINE \ --machine-key-id did:peaq:0xMACHINE#keys-1 ``` Required: `--input` (file path or `http(s)` URL), `--output-dir` (created if missing), `--owner-public-key` / `--operator-public-key` / `--machine-public-key` (X25519, 64 hex), `--signing-key-file` (Ed25519 private key file), `--machine-did`, `--machine-key-id`. Optional: `--chunk-size` (bytes, default `262144`), `--json` (emit the manifest to stdout), and S3 upload — `--s3 s3://bucket/prefix/`, `--s3-region`, `--s3-endpoint` (for MinIO / R2 / S3-compatible stores). S3 needs the extra (`pip install "peaq-os-cli[s3]"`) and credentials via `PEAQOS_S3_ACCESS_KEY_ID` + `PEAQOS_S3_SECRET_ACCESS_KEY` (or the standard boto3 chain); each chunk's `storageRef` is rewritten to its `s3://` URI. The human summary goes to stderr; the manifest path prints to stdout for piping. Exit codes: `0` success, `1` validation (bad key hex, wrong length, missing input file, `StreamValidationError`/`StreamSigningError`), `2` URL download or S3 upload failure. #### `peaqos stream grant` Grant a buyer decryption access to a published chunk chain — fully offline. Reads the chunk envelopes, unwraps each chunk key with the owner's X25519 private key, re-wraps for the buyer, and writes `peaq.stream.buyer-access.v1` files (sharded by size). This is a local re-key, not an on-chain access grant. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos stream grant \ --chunk-dir ./out \ --buyer-public-key 0x<64hex> \ --buyer-id did:peaq:0xBUYER \ --owner-private-key-file ./owner-x25519.key \ --output-dir ./buyer-access ``` Required: `--chunk-dir` (published envelopes), `--buyer-public-key` (X25519), `--buyer-id`, `--owner-private-key-file`, `--output-dir`. Optional: `--max-file-size` (bytes per access file, default `512000`), `--json` (summary with per-file listing). Exit codes: `0` success, `1` validation (invalid keys, no chunk files, malformed chunk, `--max-file-size <= 0`), `2` key-commitment mismatch — wrong owner key. #### `peaqos stream consume` Buyer-side: decrypt a purchased chunk chain and reassemble the original data. Reads the chunk envelopes, the encrypted `.bin` blobs, and the buyer access files (filtered to `--buyer-id`), verifies the chain (unless `--skip-verify`), decrypts each chunk with the buyer's X25519 private key, and writes the result to `--output`. Two input modes: * **Local** (offline) — `--chunk-dir`, `--access-dir`, and `--data-dir` point at directories already on disk. * **Remote** (`v0.0.6`+) — `--download-url` points at an HTTP/HTTPS **self-contained release package** bundling the envelopes, `.bin` blobs, and access files, exposed as a `manifest.json` file listing or a ZIP archive. The package is downloaded into a work directory (`--work-dir`, or a temp dir cleaned up after success unless `--keep-files`; preserved on any error for debugging), then the same verify → decrypt → reassemble pipeline runs. `--download-url` is mutually exclusive with the three directory flags. `--download-url` does **not** consume the pre-signed URL from `peaqos stream distribute` directly — that URL delivers only the **first** buyer-access file, while the chunk envelopes and ciphertext stay behind each chunk's `storageRef`. A full distribute → consume roundtrip needs a self-hosted bundle as described above; a buyer-side S3 receiver is not shipped yet. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Local mode — directories already on disk peaqos stream consume \ --chunk-dir ./out \ --access-dir ./buyer-access \ --data-dir ./out \ --buyer-private-key-file ./buyer-x25519.key \ --buyer-id did:peaq:0xBUYER \ --output ./recovered.bin # Remote mode — fetch a self-contained release bundle peaqos stream consume \ --download-url "https://bundles.example.com/releases/ord-001/" \ --buyer-private-key-file ./buyer-x25519.key \ --buyer-id did:peaq:0xBUYER \ --output ./recovered.bin ``` Required: `--buyer-private-key-file` (buyer X25519 private key), `--buyer-id` (must match the `recipientId` in the access files), `--output` (reassembled plaintext path), and — in local mode — `--chunk-dir` (envelopes), `--access-dir` (buyer access files), `--data-dir` (encrypted `.bin` blobs). Optional: `--download-url` (remote release package; a query token on the URL is preserved when fetching each file), `--work-dir` / `--keep-files` (remote mode only), `--skip-verify` (skip chain verification; debugging only), `--json` (summary to stdout: `output`, `totalBytes`, `chunkCount`, `sourceHash`, `buyerId`, `verified`). Exit codes: `0` success, `1` validation (empty `--buyer-id`, unreadable key, missing input files or dirs, `--download-url` combined with a directory flag or with a non-http(s) scheme), `2` decryption, integrity, or download failure (HTTP error, timeout, invalid ZIP). The buyer-side messages are specific: a wrong or ungranted key gives `Decryption failed for chunk — access not granted for this buyer private key`; a mismatched `--buyer-id` gives `No buyer access for chunk ()`; a tampered chunk gives `Data integrity check failed for chunk — plaintext hash mismatch`. #### `peaqos stream distribute` Seller-side, new in `v0.0.6`. Listen for a buyer's payment confirmation, then automatically generate buyer access files (same re-key as `stream grant`) and deliver them to S3 under `{prefix}{buyer_id}/`, returning a pre-signed download URL. Polls `--confirmation-url` every `--poll-interval` seconds (default `30`) until the endpoint reports a confirmed payment or `--timeout` seconds (default `3600`) elapse. The confirmation endpoint must return JSON with at least `status`, `buyer_id`, and `buyer_public_key_hex`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos stream distribute \ --chunk-dir ./out \ --owner-private-key-file ./owner-x25519.key \ --confirmation-url https://api.example.com/orders/ord-001/status \ --order-id ord-001 \ --delivery s3 \ --s3 s3://my-bucket/distributes/ ``` Required: `--chunk-dir` (published envelopes from `stream publish`), `--owner-private-key-file` (the X25519 key used at publish time — one line of 64 hex, optional `0x` prefix), `--confirmation-url`, `--order-id`, `--delivery` (currently only `s3`), and `--s3` (bucket path). Optional: `--poll-interval`, `--timeout`, `--s3-region`, `--s3-endpoint` (MinIO / R2 / S3-compatible), `--presign-expiry` (seconds, default `3600`), `--max-file-size` (bytes per access file, default `512000`), `--json`. S3 needs the extra (`pip install "peaq-os-cli[s3]"`) and credentials via `PEAQOS_S3_ACCESS_KEY_ID` + `PEAQOS_S3_SECRET_ACCESS_KEY` or the standard boto3 chain. Exit codes: `0` success, `1` validation (no chunk files, unreadable key, non-positive interval/timeout, `--delivery s3` without `--s3`), `2` confirmation timeout or S3 upload failure, `3` `boto3` missing. In the SDK, the same loop is [`PollingConfirmationProvider` + `distributeData`](/peaqos/sdk-reference/stream-distribution#seller-getting-paid-and-preparing-access) — where a [P2P delivery channel](/peaqos/sdk-reference/stream-distribution#p2p-delivery) can replace S3. #### `peaqos stream pay` Buyer-side, new in `v0.0.6`. Transfer tokens on-chain to a seller — native or ERC-20/SPL on `peaq`, `base`, or `solana` — and optionally submit the transaction hash as payment proof in the same run. With `--confirmation-url`, proof is submitted right after the transfer; without it, only the transfer executes and the CLI prints the matching `peaqos stream payproof` command. The tx hash is always written to stdout before the proof step, so it survives a failed proof submission. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Base USDC transfer with proof submission peaqos stream pay \ --seller-address 0xSeller... \ --amount 1.0 \ --chain base \ --order-id order-002 \ --rpc-url https://mainnet.base.org \ --token-address 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \ --confirmation-url https://api.example.com/payments/proof ``` Required: `--seller-address` (EVM `0x...` or Solana base58), `--amount` (human-readable, e.g. `"10.5"`), `--chain`, `--order-id`. Optional: `--confirmation-url`, `--token-address` (ERC-20 contract or SPL mint; omit for the native token), `--token-decimals` (override for tokens outside the well-known registry), `--rpc-url` (required for `base` and `solana`), `--private-key-file` (falls back to `PEAQOS_PRIVATE_KEY`), `--json` (`proof` is `null` when no confirmation URL was given). Exit codes: `0` success, `1` validation or signing failure (messages never contain key material; Solana support needs `pip install "peaq-os-sdk[solana]"`), `2` insufficient balance, revert, or proof HTTP failure, `3` missing config. #### `peaqos stream payproof` Buyer-side, new in `v0.0.6`. Submit payment proof for a transfer completed outside `peaqos stream pay`, or retry a proof step that failed. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos stream payproof \ --tx-hash 0xabc123... \ --order-id order-001 \ --confirmation-url https://api.example.com/payments/proof \ --chain peaq \ --payer-address 0xPayer... \ --payee-address 0xSeller... \ --amount 10.5 ``` Required: `--tx-hash` (EVM hash or Solana signature), `--order-id`, `--confirmation-url`, `--chain`, `--payer-address`, `--payee-address`, `--amount` (must match the original transfer). Optional: `--token`, `--token-address`, `--json`. Exit codes: `0` success, `1` validation, `2` proof HTTP failure, `3` missing config. ### Solana payments There is no `peaqos solana` command group, but since `v0.0.6` the CLI signs Solana transfers natively where it matters: `peaqos stream pay --chain solana` sends native or SPL transfers itself (requires `--rpc-url` and, for SPL, the mint via `--token-address`; install with `pip install "peaq-os-sdk[solana]"`). Solana-quoted **Machine Market** orders are still paid externally — complete the SPL transfer with your own Solana wallet, then pass `--payment-tx-hash` to `peaqos scale order` so the orchestrator can verify it against the quote. ### `peaqos monetize` Available since `peaq-os-cli` 0.0.7. Toggle a machine's [monetization](/peaqos/functions/monetize) on or off (signed) and read its state (public). Thin wrappers over the SDK's [opt-in client](/peaqos/sdk-reference/monetization-opt-in): the SDK signs the EIP-191 canonical message and calls the MCR API; the CLI adds parsing, prompts, and output. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos monetize opt-in [--yes] [--json] peaqos monetize opt-out [--yes] [--json] peaqos monetize status [--json] ``` `` is a machine DID or a decimal machine ID. Opting in requires the machine to be registered, bonded, and not deactivated (server-enforced); opting out is always allowed. `status` is public, needs no signing key, and is the pre-provisioning check. Signed writes require `PEAQOS_PRIVATE_KEY` (machine wallet, owner, or operator key), `PEAQOS_MCR_API_URL`, `IDENTITY_REGISTRY_ADDRESS`, and RPC access; `status` needs only the API URL and registry address. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Turn monetization on for machine 42 (prompts for confirmation) peaqos monetize opt-in 42 # Machine-readable state for jq / scripts peaqos monetize status 42 --json ``` ### `peaqos monetize provision` Provision an **opted-in** machine as a compute provider node from a schema-driven manifest, entirely from the terminal. Thin wrappers over the SDK's [manifest runner](/peaqos/sdk-reference/provisioning): every command, secret redaction, and verification probe runs inside the SDK; the CLI adds prompts, terminal rendering, and the resume state file. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos monetize provision run --machine [--mode manual|auto] [--grant-sudo] peaqos monetize provision preflight [--inputs ] peaqos monetize provision verify [--state-file ] [--json] ``` * `` is the manifest provider key (for example `akash`). Requires `PEAQOS_MANIFEST_REPO_URL` or `--manifest-repo`. * `run` walks the full flow: monetization pre-check (anything but `OPTED_IN` stops before the manifest is even fetched), manifest fetch pinned by sha256, input collection (`--inputs` file plus hidden prompts for secrets), blocking pre-flight, provisioning with a state checkpoint after each step, and verification probes that alone decide success. * `--mode manual` (default) confirms each command; `--mode auto` runs unattended and requires `--grant-sudo`, scoped to the manifest's `allowedCommands`. Owner-action handoffs (funding, DNS, signing) always pause, even with `--yes`. * `--machine` takes the DID form so the machine wallet address flows into the manifest as commission context; a numeric ID needs `PEAQOS_MACHINE_WALLET_ADDRESS` set explicitly. Note the env var wins when both are present: a set `PEAQOS_MACHINE_WALLET_ADDRESS` silently overrides the DID's embedded address, so unset it before provisioning a different machine. * `--resume` continues an interrupted run from the state file (default `./peaqos-provision-state.json`, written atomically with `0600`). Non-secret inputs are restored; secrets are re-prompted, never persisted. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Full manual run peaqos monetize provision run akash \ --machine did:peaq:0x9a5F...37C5 --inputs ./akash-inputs.yaml # Re-check a provisioned node against the pinned manifest peaqos monetize provision verify akash --json | jq '.[] | select(.passed == false)' ``` ### `peaqos scale` Machine Market orchestration commands. Pair an AI agent to an activated machine, search the curated catalogue, and drive the full purchase loop. The `peaqos scale` surface (CLI `v0.0.5`+): `agent pair`, `machine onboard` (plus `machine status` and `machine list`), `search`, and the `scale order` family — place (dispatched from a service UUID), `status`, `list` with cursor pagination, `received`, `dispute`. CLI `v0.0.6` adds the x402 payment rail to order placement. #### Setup Two new env vars, both optional in `load_client()`. Override at any point with the root-level flags `--orchestration-url` / `--orch-api-key`. | Env var | CLI override | Purpose | | :------------------------- | :-------------------------- | :------------------------------------ | | `PEAQOS_ORCHESTRATION_URL` | `--orchestration-url ` | Machine Markets API base URL | | `PEAQOS_ORCH_API_KEY` | `--orch-api-key ` | Platform API key (`x-api-key` header) | `peaqos init` prompts for both during the wizard and writes them as active `.env` lines (not commented placeholders). The API key is entered at a hidden prompt (not echoed to the terminal), then written to `.env` in plaintext, so treat the file as a secret: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Machine Market orchestration PEAQOS_ORCHESTRATION_URL=https://orchestration.peaq.xyz PEAQOS_ORCH_API_KEY= ``` `peaqos init --non-interactive` reads both from existing env vars. The pairing token returned by `agent pair` is the credential for agent-side commands. Save it once to a single-line file with `chmod 600` and reference it via `--pairing-token-file`. #### `peaqos scale machine onboard` Operator-facing. Walks a machine through the four-step orchestration onboard: request an identity challenge, sign with the DID controller key, register the machine with proof attached, then activate (unless `--skip-activate`). Hits `POST /api/v1/machine-identity/challenges` and `POST /api/v1/machines`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos scale machine onboard \ --identity-ref did:peaq:0xMachineWallet \ --display-name "rover-014" \ --owner-id op_xyz \ --machine-type qvac \ --runtime-profile machine-runtime-agent ``` Required: `--identity-ref`, `--display-name`, `--owner-id`, `--machine-type`, `--runtime-profile`. Optional: `--capabilities` (CSV), `--skill-keys` (CSV), `--labels` (`KEY=VALUE,...`), `--identity-signature-file`, `--identity-key-file`, `--skip-activate`, `--yes`, `--json`. Supply exactly one of the two signing inputs: `--identity-signature-file` if you have already signed the challenge externally (one-line hex signature), or `--identity-key-file` if you want the CLI to sign in-process with the DID controller's private key. Either is enough; supplying both is rejected. Exit codes: `0` happy path, `1` input error, `2` server / proof error (`MACHINE_IDENTITY_EXISTS`, `MACHINE_IDENTITY_PROOF_INVALID`, `PEAQOS_IDENTITY_UNAVAILABLE`). #### `peaqos scale agent pair` Operator-facing. Pairs an AI agent to a machine via a three-step challenge-sign flow. Returns a one-time signed-JWT `pairingToken`. Internally the command: 1. Calls `client.orchestration.createAgentPairingChallenge(machineId, params)` for a server-issued challenge keyed to `agentAddress`, `agentProvider`, `agentRole`, and optional `agentDid`. 2. The Machine Agent signs the returned challenge message (EIP-191) with the wallet key behind `agentAddress`. Supply the signature via `--agent-signature-file `. 3. Calls `client.orchestration.createAgentPairing(machineId, paramsWithProof)` to persist the pairing and issue the session JWT. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos scale agent pair \ --machine-id mach_61f043950cf1 \ --agent-address 0xagent...0101 \ --agent-did did:pkh:eip155:1:0xagent...0101 \ --agent-provider teneo \ --agent-role machine-market-buyer \ --agent-signature-file ~/.peaqos/agent-challenge.sig \ --per-tx-limit 5 --daily-limit 20 --currency USD \ --allowed-skills agentic-market-claude-inference,pay-sh-gemini \ --allowed-service-ids svc_abc \ --denied-service-ids svc_xyz ``` Required: `--machine-id`, `--agent-address`, `--agent-provider`, `--agent-role`. Optional: `--agent-did`, `--agent-signature-file` (path to pre-signed EIP-191 challenge signature; required with `--json`, otherwise the CLI prompts interactively), `--description`, `--per-tx-limit`, `--daily-limit`, `--currency`, `--allowed-skills` (CSV), `--denied-skills` (CSV), `--allowed-service-ids` (CSV), `--denied-service-ids` (CSV), `-y`/`--yes` to skip the confirmation prompt, `--json` for raw JSON (implies `--yes`). Preconditions: `PEAQOS_ORCH_API_KEY` set. Machine already active in peaqOS or the server returns `MACHINE_NOT_ACTIVATED` and the CLI exits 2. Output adds `Agent DID`, `Session ID`, `Session Expires`, and `Verification` lines to the existing pairing summary. The token prints exactly once on stdout, never written to `peaqos.log` or `--verbose` output. Pipe to a file: ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos scale agent pair ... --json | jq -r .pairing_token > ~/.peaqos/agent.token chmod 600 ~/.peaqos/agent.token ``` Session tokens expire (default 1 hour). Rotate directly via `client.orchestration.createAgentPairingSession(...)` from your own tooling, signing a fresh challenge. #### `peaqos scale search` Agent-facing. Posts a market search and returns ranked service quotes. Hits `POST /api/v1/market/search` plus `GET /api/v1/market/searches/:searchId`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos scale search \ --machine-id mach_1 \ --service-type oracle.price-feed \ --pairing-token-file ~/.peaqos/agent.token \ --budget-amount 1 --budget-currency USD \ --native-only ``` Required: `--machine-id`, `--service-type`, `--pairing-token-file`. Optional: `--agent-pairing-id`, `--operation`, `--capabilities` (CSV), `--region`, `--max-results`, `--budget-amount`, `--budget-max`, `--budget-currency`, `--native-only`, `--allow-handoff`, `--provider-credentials` (path to JSON), `--json`. Preconditions: machine active with verified `identityRef`, active agent pairing, pairing token in the token file. Provider credential file contents never appear on stdout, stderr, or in log output. Output: * Human mode: ranked quote table with columns `Service ID`, `Quote ID`, `Operation`, `Provider`, `Score`, `Execution`, `Integration`. Footer prints `Search ID: msearch_...` plus a concrete next-step hint: `peaqos scale order --search-id --quote-id `. * Empty results print `No matching services found.` with the same aligned `Search ID:` line and broaden-your-search guidance. * `--json` emits the full `MarketSearch` envelope. The raw `MarketSearchRequest` is constructed from typed SDK data classes, not raw dicts. The `order` group is dynamic-dispatch. Any first token that is not `status`, `list`, `received`, or `dispute` is interpreted as a service UUID and routed to the placement flow. `peaqos scale order foo-bar` reads as "place an order for service `foo-bar`." #### `peaqos scale order ` Agent-facing. End-to-end purchase. Hits the [`POST /market/orders` + payment intent + execute](/peaqos/api-reference/machine-markets-orders) flow. Four payment paths chosen from the `MarketPayment` returned at order create: * **No payment** — create → execute (2 steps). * **Wallet payment** — create → intent → transfer → proof → execute (5 steps). If `PEAQOS_OWS_WALLET` is set the CLI auto-signs the ERC-20 transfer via OWS; otherwise it prompts for a pasted tx hash (or use `--payment-tx-hash`). * **Escrow / handoff** — same five steps with the escrow rail. * **x402** (`v0.0.6`+) — create → intent → sign → proof → execute → confirm (6 steps), for paid-HTTP Agentic Market providers (e.g. Wolfram Alpha over USDC on Base). The CLI signs the provider's payment challenge locally with the active wallet (`client.account` — the OWS wallet when `PEAQOS_OWS_WALLET` is set, otherwise the local key) and hands the signed `PAYMENT-SIGNATURE` header to peaqOS, which pays the provider during execute. **No separate on-chain transfer**, no tx-hash prompt; delivery is confirmed automatically in step 6. If execution fails after proof is recorded, the error reports the current payment status so you can check whether the authorization is held. Set `PEAQOS_ORDER_STEP_DELAY_SEC` to a non-negative number of seconds to pause between placement steps (demos, eventually-consistent order state); unset means no delay. Required: `--machine-id`, `--agent-pairing-id`, `--pairing-token-file`. Optional: `--search-id`, `--quote-id`, `--operation`, `--budget-amount`, `--budget-currency`, `--input ` (JSON object file — there is no `@file` shorthand), `--provider-credentials ` (JSON file with provider creds; never logged), `--payment-tx-hash`, `--payment-chain` (CAIP-2 alias: `base`, `peaq`, `agung`, `ethereum`/`eth`, `polygon`, `arbitrum`, `optimism`, `bsc`, `solana`), `--payment-token`, `--skip-payment`, `-y`/`--yes`, `--json`. `PEAQOS_RPC_URL` overrides the built-in payment RPC list (peaq uses public Agung wss-async by default). Error codes: `QUOTE_EXPIRED`, `EXECUTION_UNSUPPORTED`, `PAYMENT_REQUIRED`, `PAYMENT_RPC_ERROR`, `PAYMENT_TX_FAILED`, `PAYMENT_TRANSFER_NOT_FOUND`, `ORDER_CLOSED`, `ORDER_NOT_DELIVERED`, `NOT_FOUND`. `--json` does not silence progress. Progress prints to stderr; the JSON envelope goes to stdout. Global `--quiet` suppresses stderr. #### `peaqos scale order status ` Returns current state of the purchase. Read-only platform auth. Hits [`GET /market/orders/:orderId`](/peaqos/api-reference/machine-markets-orders) plus the payment lookup. Optional: `--json` for the `{ order, payment }` envelope. Missing payment record (`NOT_FOUND`) is not an error — `payment` is `null` in the JSON envelope. Missing order ID exits 1. #### `peaqos scale order list --machine-id ` Lists orders for a machine. Hits [`GET /market/orders?machineId=...`](/peaqos/api-reference/machine-markets-orders). Required: `--machine-id`. Optional: `--limit ` (1-500; outside range exits 1), `--cursor ` (from a prior `next_cursor`; never logged), `--json`. Output behaviour: * Human mode: one page, `N order(s) shown.` footer. When `next_cursor` is set, the CLI prints a copy-paste hint: `Next page: peaqos scale order list --machine-id [--limit N] --cursor `. * `--json` without `--limit`: auto-paginates all pages and emits a flat root-level JSON array. * `--json` with `--limit`: emits a single-page envelope `{ "items": [...], "next_cursor": ... }`. The CLI surfaces `next_cursor` (snake\_case) on stdout; the wire field is `nextCursor`. #### `peaqos scale order received ` Confirms delivery and releases escrow. Requires `--pairing-token-file`. Hits [`POST /market/orders/:orderId/confirm`](/peaqos/api-reference/machine-markets-orders). Optional: `--json`. Status moves to `confirmed`, payment to `release_pending`. Error codes: `ORDER_NOT_DELIVERED`, `ORDER_CLOSED`, `AGENT_AUTH_INVALID`. Missing order ID or token file exits 1. #### `peaqos scale order dispute ` Raises a dispute. Requires `--reason` and `--pairing-token-file`. Hits [`POST /market/orders/:orderId/dispute`](/peaqos/api-reference/machine-markets-orders). Optional: `--evidence ` (JSON object file), `-y`/`--yes` to skip the `Raise dispute? [y/N]` prompt, `--json` (also skips the prompt). Status moves to `disputed`, payment to `frozen`. Error codes: `ORDER_CLOSED`, `AGENT_AUTH_INVALID`. Missing order ID, reason, or token file exits 1. ## Exit codes Every subcommand funnels SDK and network exceptions through a single error handler that raises with a stable exit code. | Exit code | Meaning | | :-------- | :----------------------------------------------------------------- | | `0` | Success | | `1` | User / validation error (bad flag, invalid DID, cap or rate limit) | | `2` | Network, RPC, or on-chain error (connection failure, HTTP, revert) | | `3` | Configuration error (missing env var, invalid private key file) | ## See also The peaqOS agent skill that drives these CLI flows from any AI agent. The TypeScript / Python API the CLI wraps. The MCR API that `get-mcr`, `get machine`, and `operator machines` hit.