Install
peaq-os-sdk 0.6.0 or 0.7.0, which import only on 3.12; 0.7.1 runs on 3.10 again.) Ships to PyPI as peaq-os-cli and exposes the peaqos command. Wraps the Python SDK: same on-chain path, scripted.
CLI 0.0.8 (2026-09-04) is the Economics 2.0 release.
peaqos activate is one atomic transaction with a new flag set, peaqos machine is new, and peaqos monetize targets the 2.0 MCR. There is no Tokenomics 1.0 onboarding path left in the CLI; peaqos qualify and peaqos show cannot address 2.0 machines yet (see below). To drive 1.0 machines from the terminal, pin pip install "peaq-os-cli<0.0.8" "peaq-os-sdk<0.6.0" (Python 3.11 or newer). The CLI pin alone resolves to CLI 0.0.7 with SDK 0.7.0, and peaqos monetize then crashes with a TypeError.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 <url> and --orch-api-key <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..env interactively with peaqos init.
Commands
peaqos init
Interactive wizard that scaffolds a .env with the required peaqOS variables. Prompts for network, source (paste, generate, or wallet), RPC URL, the Economics 2.0 deployment ID (TOKENOMICS_DEPLOYMENT_ID, default peaq-mainnet on mainnet and agung-2026-08-28 on testnet), MCR API URL, URL, the six Tokenomics 1.0 contract addresses (labelled legacy, still required by the SDK constructor), 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 and writes PEAQOS_OWS_WALLET=<name> instead of PEAQOS_PRIVATE_KEY. Writes .env with 0o600 permissions and auto-runs whoami to verify.
peaqos whoami
Read-only command that prints the , network, , RPC + MCR API URLs, the legacy from .env, and a Tokenomics 2.0: block with the deployment ID, chain ID, and the five addresses the SDK record resolved (these come from the SDK, not from .env). Useful as a sanity check after init.
peaqos activate
Upgrade the SDK underneath the CLI.
InfoDesk re-pointed MACHINE_BRIDGE_ADAPTER on 2026-09-08 and peaq-os-sdk 0.7.1 (2026-09-11) carries the new address. A fresh pip install peaq-os-cli resolves 0.7.1 and passes preflight. An environment installed before 2026-09-11 fails every peaq-mainnet write with PEER_MISMATCH until you run pip install -U peaq-os-sdk.MachineStateAndSync.activateMachine mints the ERC-721, stores the DID document, bonds the subscription tier, and registers the home chain in a single call. Mirrors the Activate flow. Requires TOKENOMICS_DEPLOYMENT_ID.
The transaction sender becomes the machine’s owner and bond payer. The bond is quoted in PEAQ per tier at the oracle rate; --payment chooses what settles it.
Flags
--machine-type and --credential-subject-hex alone determine the machine ID (uint256(keccak256(abi.encode(machineType, credentialSubject)))). Neither can change after activation, and the same pair can never be activated twice.
Private keys must come from a file. Inline key flags are intentionally unsupported: a file keeps the key out of shell history and ps output.
DID document schema
Exactly three root fields, all required. Unknown fields, duplicate keys, and a rootid or controller are rejected: id is computed on-chain and controller is set by the CLI from the mode.
authentication entry is an index into verificationMethods. The CLI bounds-checks them because the contract stores them unchecked at mint.
Ownership modes
In machine-key mode the CLI prints the changed rights before asking: the machine wallet can transfer the NFT and rotate or clear the controller; the operator can run lifecycle, subscription, and DID actions but cannot transfer the NFT or change the controller. There is no operator-sponsored activation;
registerFor has no 2.0 equivalent.
Paying in USDT
The bond, the voucher credit, and the net amount stay in PEAQ; only settlement differs. The CLI shows the USDT token, the quote, the accepted slippage, and the resulting maximum USDT, then submits that exact maximum. The allowance goes toSubscriptionTokenProvisionPool, not to MachineSubscription. A bond covered entirely by voucher credit converts and transfers nothing.
Output, exit codes, and error_code
Progress, the preview, and prompts go to stderr; stdout carries only the final summary (or one JSON object with --json). Machine IDs and every unbounded chain integer are decimal strings in JSON, never numbers.
activate outcome is a JSON report (with --json) whose failures carry a stable error_code, bracketed in human output; success and preview reports set error_code to null and report a status instead: preview, activated, already_active, or pending. Input and flag errors before that point exit 1 with a plain message and no report. The codes to know:
Pending transactions and peaqos.log
A submitted transaction whose receipt does not arrive is reported as PENDING at exit 2 with its hash, not as a failure. It may still mine. Every submitted hash is appended to ./peaqos.log (mode 0600) before the receipt wait. Re-running the same command reconciles the recorded hash instead of resubmitting; a hash with no receipt blocks resubmission regardless of age. Never submit a second activation for the same machine, and never delete peaqos.log while a transaction is outstanding.
peaqos machine
New in 0.0.8. Everything after onboarding: lifecycle, subscription payments, ERC-721 ownership, DID updates, and relocation status. Requires TOKENOMICS_DEPLOYMENT_ID.
--yes and --json; every read accepts --json. Machine IDs are full-width uint256: pass them as canonical unsigned decimal (no 0x, no leading zeros) and read them back as decimal strings.
Every write runs the same sequence: validate locally, reconcile the journal (a pending transaction for the same action and machine blocks rather than repeats), ask the SDK for a preview (chain, contract, method, current state, intended effect), show it and ask, then submit once and record the hash before waiting for the receipt. Reruns reconcile the recorded hash and never resubmit.
Details that matter:
- Who may sign. Suspend, resume, renew, and DID updates: owner or controller.
set-controllerandclear-controller: owner only. Transfers: standard ERC-721 authority. Points and credits from a renewal land on the owner even when the controller pays. approve-allis not scoped to one machine. It grants the operator every MachineRegistry machine the signer owns, including ones activated later.transferis safe by default (safeTransferFrom).--unsafeselectstransferFrom, which can strand the NFT in an incompatible contract. Transfer does not rotate the DID controller.- DID setters replace whole arrays. The file or index list you pass is the complete new state. Authentication indices point into the verification-method array by position.
--indexand--clearare mutually exclusive and one is required. - Renewal takes no
--tier. The contract renews at the stored tier and extends from the current period end, not from now.--payment usdtrequires--slippage-bps. - Relocation is read-only.
relocation statusreportspending,arrived,completed,cancelled, orconflicting. Initiation and cancellation are absent until the protocol publishes a fee quote; relocation is also disabled on chain today.
error_code values are the ones documented under peaqos activate: one taxonomy for both.
peaqos qualify event
Submit a revenue or activity event to the EventRegistry. Wraps submit_event. See the Submit events guide for and patterns.
--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.
Human output on success:
peaqos qualify mcr
Fetch a machine’s credit rating from the MCR API. Wraps query_mcr.
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:
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):
peaqos show machine
Fetch a full machine profile: Machine ID, operator, DID attributes, MCR snapshot, recent events. Wraps query_machine.
peaqos show operator machines
List the machines registered under a proxy operator, with MCR per machine. Wraps query_operator_machines.
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 is read from OWS_PASSPHRASE when set, otherwise prompted interactively. Subcommands wrap the SDK static helpers documented on Wallets (OWS).
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; the SDK-level P2P delivery channel 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).
--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.
--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-dirpoint at directories already on disk. - Remote (
v0.0.6+) —--download-urlpoints at an HTTP/HTTPS self-contained release package bundling the envelopes,.binblobs, and access files, exposed as amanifest.jsonfile 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-urlis mutually exclusive with the three directory flags.
--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 <index> — access not granted for this buyer private key; a mismatched --buyer-id gives No buyer access for chunk <index> (<chunk-id>); a tampered chunk gives Data integrity check failed for chunk <index> — 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.
--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 — where a P2P delivery channel 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.
--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.
--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 nopeaqos 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
Manage a machine’s Economics 2.0 monetization decision in the MCR: status is a public read; opt-in and opt-out are signed, off-chain decisions. Thin wrappers over the SDK’s opt-in client: the SDK runs the compatibility check, EIP-191 signing, retries, HTTP, and response validation; the CLI adds parsing, prompts, and output.
KEY is a canonical decimal machine ID or did:peaq:<decimal machine id>. Address DIDs (did:peaq:0x…), leading zeros, signs, hex, and exponents are rejected locally: there is no translation from a 1.0 address DID to a 2.0 machine ID.
Every command requires TOKENOMICS_DEPLOYMENT_ID. The SDK resolves the MCR URL, chain ID, MachineRegistry, and API version from that deployment and the server’s live compatibility signal (GET /.well-known/peaq-monetization). PEAQOS_MCR_API_URL, IDENTITY_REGISTRY_ADDRESS, and PEAQOS_RPC_URL are not read; an explicit --api-url exits 3. status needs no signer; writes need PEAQOS_PRIVATE_KEY, and the recovered address must be the machine’s current owner or DID controller (a machine-wallet-only key or a 1.0 operator key is not authorized).
Before a write the CLI reads the current state; an already-satisfied state returns without a prompt, signature, or PUT. Only 503 MACHINE_UNAVAILABLE is retried. A timeout during a PUT is ambiguous (the MCR may have applied it): rerun the same command, which reads first and sends no second PUT if the state is already there.
PENDING; Tokenomics 1.0 decisions and signatures are not imported.
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: every command, secret redaction, and verification probe runs inside the SDK; the CLI adds prompts, terminal rendering, and the resume state file.
<provider>is the manifest provider key (for exampleakash). RequiresPEAQOS_MANIFEST_REPO_URLor--manifest-repo.runwalks the full flow: monetization pre-check (anything butOPTED_INstops before the manifest is even fetched), manifest fetch pinned by sha256, input collection (--inputsfile 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 autoruns unattended and requires--grant-sudo, scoped to the manifest’sallowedCommands. Owner-action handoffs (funding, DNS, signing) always pause, even with--yes.--machinetakes a decimal machine ID ordid:peaq:<decimal id>(0.0.8; address DIDs are rejected), so the machine wallet address for the manifest’s commission context must come fromPEAQOS_MACHINE_WALLET_ADDRESS. Unset it before provisioning a different machine. The monetization pre-check goes through the 2.0 SDK read and is blocked by the same missing 2.0 MCR aspeaqos monetizetoday.--resumecontinues an interrupted run from the state file (default./peaqos-provision-state.json, written atomically with0600). Non-secret inputs are restored; secrets are re-prompted, never persisted.
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 payment rail to order placement.
Setup
Two new env vars, both optional inload_client(). Override at any point with the root-level flags --orchestration-url / --orch-api-key.
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:
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 , 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.
--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:
- Calls
client.orchestration.createAgentPairingChallenge(machineId, params)for a server-issued challenge keyed toagentAddress,agentProvider,agentRole, and optionalagentDid. - The Machine Agent signs the returned challenge message () with the wallet key behind
agentAddress. Supply the signature via--agent-signature-file <path>. - Calls
client.orchestration.createAgentPairing(machineId, paramsWithProof)to persist the pairing and issue the session JWT.
--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:
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.
--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 printsSearch ID: msearch_...plus a concrete next-step hint:peaqos scale order <service-id> --search-id <search-id> --quote-id <quote-id>. - Empty results print
No matching services found.with the same alignedSearch ID:line and broaden-your-search guidance. --jsonemits the fullMarketSearchenvelope. The rawMarketSearchRequestis constructed from typed SDK data classes, not raw dicts.
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 <service-uuid>
Agent-facing. End-to-end purchase. Hits the POST /market/orders + payment intent + execute 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_WALLETis 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 .
- 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 whenPEAQOS_OWS_WALLETis set, otherwise the local key) and hands the signedPAYMENT-SIGNATUREheader 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.
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 <path> (JSON object file — there is no @file shorthand), --provider-credentials <path> (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 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 <order-id>
Returns current state of the purchase. Read-only platform auth. Hits GET /market/orders/:orderId 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 <id>
Lists orders for a machine. Hits GET /market/orders?machineId=....
Required: --machine-id.
Optional: --limit <int> (1-500; outside range exits 1), --cursor <opaque> (from a prior next_cursor; never logged), --json.
Output behaviour:
- Human mode: one page,
N order(s) shown.footer. Whennext_cursoris set, the CLI prints a copy-paste hint:Next page: peaqos scale order list --machine-id <id> [--limit N] --cursor <verbatim>. --jsonwithout--limit: auto-paginates all pages and emits a flat root-level JSON array.--jsonwith--limit: emits a single-page envelope{ "items": [...], "next_cursor": ... }.
next_cursor (snake_case) on stdout; the wire field is nextCursor.
peaqos scale order received <order-id>
Confirms delivery and releases escrow. Requires --pairing-token-file. Hits POST /market/orders/:orderId/confirm.
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 <order-id>
Raises a dispute. Requires --reason and --pairing-token-file. Hits POST /market/orders/:orderId/dispute.
Optional: --evidence <path> (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.peaqos activate adds a stable error_code to every failure after input validation (see peaqos activate). peaqos machine and peaqos monetize print the error message only, also with --json (checked on 0.0.8 with machine status and monetize status against unknown machine IDs).
See also
peaqOS AI
The peaqOS agent skill that drives these CLI flows from any AI agent.
SDK reference
The TypeScript / Python API the CLI wraps.
API reference
The MCR API that
get-mcr, get machine, and operator machines hit.
