Skip to main content
The peaqOS CLI wraps the into a terminal surface for the most common machine flows: activating a machine under Economics 2.0, managing its lifecycle and subscription, submitting events, querying , running fleets, and the full Scale loop: an , searching the catalogue, placing and confirming orders. It’s the same and orchestration path as the JS and Python SDKs, scripted.

Install

Python 3.10 or newer. (0.0.8 installs made before 2026-09-11 resolved 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.
Other are available. See 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, 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.
EVENT_REGISTRY_ADDRESS is the one legacy address the wizard does not fill in. The other five come from the network defaults; the Event Registry prompt has no default, and --non-interactive writes whatever EVENT_REGISTRY_ADDRESS holds in your shell, empty if unset. With an empty value every command that builds an SDK client exits 3 with Missing required env var: EVENT_REGISTRY_ADDRESS. Export it before running the wizard or fill the line in .env afterwards; the addresses are in the install page tables.

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.
Onboard a machine in one atomic transaction. 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.
Removed in 0.0.8: --doc-url, --data-api, and --visibility. They wrote DID attributes after registration; 2.0 records the DID document atomically during activation. Passing any of them exits 1 with a plain error message (no error_code). Put documentation and API URLs into the serviceEndpoints array of --did-document.

DID document schema

Exactly three root fields, all required. Unknown fields, duplicate keys, and a root id or controller are rejected: id is computed on-chain and controller is set by the CLI from the mode.
Each 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 to SubscriptionTokenProvisionPool, 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.
The four CLI-wide exit codes apply. Once input validation has passed, every 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.
Every write accepts --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-controller and clear-controller: owner only. Transfers: standard ERC-721 authority. Points and credits from a renewal land on the owner even when the controller pays.
  • approve-all is not scoped to one machine. It grants the operator every MachineRegistry machine the signer owns, including ones activated later.
  • transfer is safe by default (safeTransferFrom). --unsafe selects transferFrom, 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. --index and --clear are 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 usdt requires --slippage-bps.
  • Relocation is read-only. relocation status reports pending, arrived, completed, cancelled, or conflicting. Initiation and cancellation are absent until the protocol publishes a fee quote; relocation is also disabled on chain today.
Exit codes and error_code values are the ones documented under peaqos activate: one taxonomy for both.
qualify and show cannot address 2.0 machines in CLI 0.0.8. The CLI accepts only did:peaq:0x<address> DIDs, while the SDK in Tokenomics mode (peaq-os-sdk 0.7.1, which now serves 2.0 queries from mcr-20.peaq.xyz and enables 2.0 event submission) accepts only did:peaq:<decimal machine id>. With TOKENOMICS_DEPLOYMENT_ID set, a decimal DID is rejected by the CLI and a hex DID by the SDK, so qualify mcr, show machine and show operator machines exit with a validation error. Mode-aware DID handling is in the next CLI release (0.0.9, in progress on 2026-09-11). To read 1.0 machines, unset TOKENOMICS_DEPLOYMENT_ID in a separate shell, or pin peaq-os-cli<0.0.8 together with peaq-os-sdk<0.6.0. Until 0.0.9, submit 2.0 events and read 2.0 ratings through the SDKs.

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.
The 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:
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).
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.
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.
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 <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.
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 — 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.
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.
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

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.
Live on peaq-mainnet since 2026-09-05. The 2.0 MCR at https://mcr-20.peaq.xyz publishes the /.well-known/peaq-monetization signal and serves the mirrored 2.0 machines; peaqos monetize status <decimal id> returns PENDING for a machine that has never opted in (checked 2026-09-05 14:00 UTC, reads only). agung-2026-08-28 has no paired MCR and exits 3 with DEPLOYMENT_UNAVAILABLE. To toggle monetization on a Tokenomics 1.0 machine, pin pip install "peaq-os-cli<0.0.8" "peaq-os-sdk<0.6.0", which talks to mcr.peaq.xyz. The CLI pin alone pulls SDK 0.7.0, and peaqos monetize then crashes with a TypeError before it reaches the server.
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.
2.0 state starts at 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 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 a decimal machine ID or did:peaq:<decimal id> (0.0.8; address DIDs are rejected), so the machine wallet address for the manifest’s commission context must come from PEAQOS_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 as peaqos monetize today.
  • --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.

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 in load_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.
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 () with the wallet key behind agentAddress. Supply the signature via --agent-signature-file <path>.
  3. Calls client.orchestration.createAgentPairing(machineId, paramsWithProof) to persist the pairing and issue the session JWT.
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:
Session tokens expire (default 1 hour). Rotate directly via client.orchestration.createAgentPairingSession(...) from your own tooling, signing a fresh challenge. Agent-facing. Posts a market search and returns ranked service quotes. Hits POST /api/v1/market/search plus GET /api/v1/market/searches/:searchId.
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 <service-id> --search-id <search-id> --quote-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 <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_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 .
  • 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 <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. When next_cursor is set, the CLI prints a copy-paste hint: Next page: peaqos scale order list --machine-id <id> [--limit N] --cursor <verbatim>.
  • --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 <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.