peaqOS CLI

The peaqOS CLI wraps the SDK into a terminal surface for the most common machine flows: registering a machine, submitting events, querying credit ratings, and managing proxy-operator fleets. It’s the same on-chain 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).

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 RPC endpoints 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, private key source (paste, generate, or wallet), RPC URL, MCR API URL, Gas Station URL, and Event Registry address. The wallet path creates a new OWS vault wallet 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 signing address, network, chain ID, RPC + MCR API URLs, and all peaqOS contract addresses the CLI is configured with. Useful as a sanity check after init.

peaqos whoami

`peaqos activate`

Register a machine on peaq end-to-end: balance check, Gas Station funding (when 2FA is configured), register_machine, mint the Machine NFT, write DID attributes. Idempotent: safe to re-run if a step fails. Mirrors the Activate 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 operator to already be registered on IdentityRegistry (i.e. have run peaqos activate in self mode first). If not, the command exits 2 before spending any gas.

Output streams

The final summary (Machine ID, Token ID, Machine DID; plus Machine Address and Operator DID in proxy mode) goes to stdout so it can be piped or captured. Progress lines ([1/6], [2/6], …) and per-step info/warning messages go to stderr.

Idempotent rerun

Every mutating step does a read-before-write precheck. Re-running peaqos activate against state that’s already complete submits no transactions and exits 0. A TOCTOU revert (AlreadyRegistered / AlreadyExists) is recovered as a skip rather than surfaced as a network error.

`peaqos.log`

Every step appends a JSONL entry to ./peaqos.log (0o600) in the working directory: a resume marker for partial failures and the audit trail.

{"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 trust levels and cross-chain 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 DID must match did:peaq:0x plus 40 hex characters. --json emits the raw SDK response on stdout with no banner or prose: useful for jq and scripting. Human output:

MCR for did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5

  Rating:          A
  Score:           82 / 100
  Bond Status:     bonded

  Events:
    Total:         150
    Revenue:       120
    Activity:      30

  30-Day Revenue:  up
  Last Updated:    2026-04-20T14:30:00Z
  FX Degraded:     no

revenue_trend is one of up, stable, down, or insufficient (returned when there isn’t enough revenue history to compute a trend). FX Degraded: reflects the top-level mcr_degraded field — yes when one or more scored events used a stale or unavailable FX snapshot, no otherwise. --json output (raw SDK MCRResponse):

{
  "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]. The vault passphrase 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.

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.

Welcome

Get Started

Concepts

Functions

Guides

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`

Exit codes

See also

peaqOS AI

SDK reference

API reference

Welcome

Get Started

Concepts

Functions

Guides

Documentation Index

​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

​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`

Exit codes

See also