peaqOS CLI - peaq

The peaqOS CLI wraps the into a terminal surface for the most common machine flows: registering a machine, submitting events, querying , managing 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

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: 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 <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.

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 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, MCR API URL, 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 and writes PEAQOS_OWS_WALLET=<name> instead of PEAQOS_PRIVATE_KEY. Writes .env with 0o600 permissions and auto-runs whoami to verify.

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 , network, , RPC + MCR API URLs, and all peaqOS the CLI is configured with. Useful as a sanity check after init.

peaqos whoami

`peaqos activate`

Register a machine on peaq end-to-end: balance check, Gas Station funding (when 2FA is configured), register_machine, the , write . Idempotent: safe to re-run if a step fails. Mirrors the Activate flow.

# 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 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 .

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 and exits 0. A TOCTOU (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.

{"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. See the Submit events guide for and patterns.

# 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. Wraps query_mcr.

peaqos qualify mcr did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5
peaqos qualify mcr did:peaq:0x9a5F... --json

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:

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):

{
  "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 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 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 is read from OWS_PASSPHRASE when set, otherwise prompted interactively. Subcommands wrap the SDK static helpers documented on Wallets (OWS).

Subcommand	Purpose
`peaqos wallet create <name> [--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 <name> --mnemonic [--index N] [--json]`	Import from an existing BIP-39 mnemonic (hidden prompt). `--index` selects the derivation index (default `0`).
`peaqos wallet import <name> --private-key-file <path> [--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 <name-or-id> [--json]`	Wallet metadata plus the full multi-chain address table.
`peaqos wallet export <name-or-id>`	Reveal the recovery phrase / private key. Requires interactive confirmation. Secret prints to stdout; warning prints to stderr.
`peaqos wallet delete <name-or-id>`	Securely delete a wallet (file overwritten with random bytes before unlink). Requires confirmation.
`peaqos wallet use <name-or-id>`	Set the active wallet. Writes `PEAQOS_OWS_WALLET=<name>` 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; 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).

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.

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.

# 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 <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.

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 — 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.

# 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.

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 on or off (signed) and read its state (public). Thin wrappers over the SDK’s opt-in client: the SDK signs the EIP-191 canonical message and calls the MCR API; the CLI adds parsing, prompts, and output.

peaqos monetize opt-in  <key> [--yes] [--json]
peaqos monetize opt-out <key> [--yes] [--json]
peaqos monetize status  <key> [--json]

<key> 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.

# 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: every command, secret redaction, and verification probe runs inside the SDK; the CLI adds prompts, terminal rendering, and the resume state file.

peaqos monetize provision run       <provider> --machine <key> [--mode manual|auto] [--grant-sudo]
peaqos monetize provision preflight <provider> [--inputs <file>]
peaqos monetize provision verify    <provider> [--state-file <path>] [--json]

<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 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.

# 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 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 <url>`	Machine Markets API base URL
`PEAQOS_ORCH_API_KEY`	`--orch-api-key <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:

# Machine Market orchestration
PEAQOS_ORCHESTRATION_URL=https://orchestration.peaq.xyz
PEAQOS_ORCH_API_KEY=<your-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 , 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.

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:

Calls client.orchestration.createAgentPairingChallenge(machineId, params) for a server-issued challenge keyed to agentAddress, agentProvider, agentRole, and optional agentDid.
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.

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:

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.

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 <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.

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)

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.

​Install

​Configure

​Commands

​peaqos init

​peaqos whoami

​peaqos activate

​Flags

​Output streams

​Idempotent rerun

​peaqos.log

​peaqos qualify event

​peaqos qualify mcr

​peaqos show machine

​peaqos show operator machines

​peaqos wallet

​peaqos stream

​peaqos stream publish

​peaqos stream grant

​peaqos stream consume

​peaqos stream distribute

​peaqos stream pay

​peaqos stream payproof

​Solana payments

​peaqos monetize

​peaqos monetize provision

​peaqos scale

​Setup

​peaqos scale machine onboard

​peaqos scale agent pair

​peaqos scale search

​peaqos scale order <service-uuid>

​peaqos scale order status <order-id>

​peaqos scale order list --machine-id <id>

​peaqos scale order received <order-id>

​peaqos scale order dispute <order-id>

​Exit codes

​See also

peaqOS AI

SDK reference

API reference

Install

Configure

Commands

`peaqos init`

`peaqos whoami`

`peaqos activate`

Flags

Output streams

Idempotent rerun

`peaqos.log`

`peaqos qualify event`

`peaqos qualify mcr`

`peaqos show machine`

`peaqos show operator machines`

`peaqos wallet`

`peaqos stream`

`peaqos stream publish`

`peaqos stream grant`

`peaqos stream consume`

`peaqos stream distribute`

`peaqos stream pay`

`peaqos stream payproof`

Solana payments

`peaqos monetize`

`peaqos monetize provision`

`peaqos scale`

Setup

`peaqos scale machine onboard`

`peaqos scale agent pair`

`peaqos scale search`

`peaqos scale order <service-uuid>`

`peaqos scale order status <order-id>`

`peaqos scale order list --machine-id <id>`

`peaqos scale order received <order-id>`

`peaqos scale order dispute <order-id>`

Exit codes

See also