> ## Documentation Index > Fetch the complete documentation index at: https://docs.peaq.xyz/llms.txt > Use this file to discover all available pages before exploring further. # peaqOS CLI > Drive activate, qualify, and operator flows from your terminal. 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](/peaqos/sdk-reference/sdk-js) and [Python](/peaqos/sdk-reference/sdk-python) SDKs, scripted. ## Install ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} pip install peaq-os-cli peaqos --version ``` Python 3.10+ required. Ships to PyPI as `peaq-os-cli` and exposes the `peaqos` command. Wraps the [Python SDK](/peaqos/sdk-reference/sdk-python): same on-chain path, scripted. `peaqos --version` prints both the CLI and the underlying `peaq_os_sdk` versions on a single line. Global flags `-v` / `--verbose` and `-q` / `--quiet` toggle DEBUG and ERROR-only logging respectively (mutually exclusive; logs go to stderr). ## Configure The CLI reads the same environment variables as the SDKs. Full table on [Install](/peaqos/install#environment-variables). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} export PEAQOS_RPC_URL=https://peaq.api.onfinality.io/public export PEAQOS_PRIVATE_KEY=0x... # Defaults to http://127.0.0.1:8000 (self-hosted MCR). # Set to the public peaq MCR for mainnet reads. export PEAQOS_MCR_API_URL=https://mcr.peaq.xyz ``` Other RPC endpoints are available. See [Public RPC endpoints](/peaqos/install#public-rpc-endpoints). Or scaffold a `.env` interactively with `peaqos init`. ## Commands ### `peaqos init` Interactive wizard that scaffolds a `.env` with the required peaqOS variables. Prompts for network, private key source (`paste`, `generate`, or `wallet`), RPC URL, MCR API URL, Gas Station URL, and Event Registry address. The `wallet` path creates a new OWS vault wallet and writes `PEAQOS_OWS_WALLET=` instead of `PEAQOS_PRIVATE_KEY`. Writes `.env` with `0o600` permissions and auto-runs `whoami` to verify. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos init peaqos init --force # overwrite existing .env without prompt peaqos init --non-interactive # read all values from env vars ``` ### `peaqos whoami` Read-only command that prints the signing address, network, chain ID, RPC + MCR API URLs, and all peaqOS contract addresses the CLI is configured with. Useful as a sanity check after `init`. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos whoami ``` ### `peaqos activate` Register a machine on peaq end-to-end: balance check, Gas Station funding (when 2FA is configured), `register_machine`, mint the Machine NFT, write DID attributes. Idempotent: safe to re-run if a step fails. Mirrors the [Activate](/peaqos/functions/activate) flow. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # Self-managed: caller's own key drives every step peaqos activate --doc-url "https://example.com/docs" --data-api "https://example.com/events" # Proxy-managed: caller activates on behalf of a machine EOA that signs its own DID writes peaqos activate --for 0xMachineAddress --machine-key ./machine.key --doc-url "https://example.com/docs" --data-api "https://example.com/events" ``` #### Flags | Flag | Required | Meaning | | :--------------- | :------- | :------------------------------------------------------------------------------ | | `--for` | no | Machine EOA address. Presence switches to proxy mode; requires `--machine-key`. | | `--machine-key` | no | Path to a file containing the machine's `0x`-prefixed hex private key. | | `--doc-url` | yes | Documentation URL written to the machine DID. | | `--data-api` | yes | Raw data API URL written to the machine DID. | | `--visibility` | no | Data visibility: `public` (default), `private`, or `onchain`. | | `--skip-funding` | no | Skip steps 1–3 (balance check, 2FA enrollment, Gas Station funding). | Private keys must be supplied via file path (`--machine-key`). Inline key flags are intentionally unsupported: reading from a file keeps the key out of shell history and `ps` output. **Proxy preconditions.** Proxy mode requires the operator to already be registered on `IdentityRegistry` (i.e. have run `peaqos activate` in self mode first). If not, the command exits `2` before spending any gas. #### Output streams The final summary (`Machine ID`, `Token ID`, `Machine DID`; plus `Machine Address` and `Operator DID` in proxy mode) goes to **stdout** so it can be piped or captured. Progress lines (`[1/6]`, `[2/6]`, …) and per-step info/warning messages go to **stderr**. #### Idempotent rerun Every mutating step does a read-before-write precheck. Re-running `peaqos activate` against state that's already complete submits no transactions and exits `0`. A TOCTOU revert (`AlreadyRegistered` / `AlreadyExists`) is recovered as a skip rather than surfaced as a network error. #### `peaqos.log` Every step appends a JSONL entry to `./peaqos.log` (`0o600`) in the working directory: a resume marker for partial failures and the audit trail. ```jsonl theme={"theme":{"light":"github-light-default","dark":"github-dark"}} {"address":"0xDC5b...","machine_id":42,"mode":"self","status":"confirmed","step":"register","ts":"2026-04-23T15:00:18.482917+00:00"} {"machine_id":42,"recipient":"0xDC5b...","status":"confirmed","step":"mint_nft","token_id":11,"tx_hash":"0xminttx...","ts":"..."} {"machine_did_tx_count":6,"machine_id":42,"mode":"self","status":"confirmed","step":"machine_did","token_id":11,"tx_hash":"0xdidtx...","ts":"..."} ``` Keys are alphabetically sorted on disk (`json.dumps(..., sort_keys=True)`); `ts` is the UTC `datetime.isoformat()` (`+00:00` suffix, microseconds included) and sits where the alphabetic order puts it on each line (last for most rows). `status` is one of `pending` / `skipped` / `failed` / `confirmed`. On rerun, the same rows reappear as `"status":"skipped"` and, for DID writes, with `"recovered_from":"AttributeAlreadyOnChain"`. Fund-step retries with the same `request_id` carry `"resumed_from":"pending"` on the new `pending` row instead. ### `peaqos qualify event` Submit a revenue or activity event to the EventRegistry. Wraps [`submit_event`](/peaqos/sdk-reference/sdk-python#submit_event). See the [Submit events guide](/peaqos/guides/submit-events) for trust levels and cross-chain patterns. ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} # HK$1.23 (123 cents) revenue event peaqos qualify event \ --machine-id 42 \ --type revenue \ --value 123 \ --ts 2026-04-23T12:00:00Z \ --trust self \ --source-chain peaq ``` `--value` is an ISO 4217 minor-unit integer: cents for USD/HKD, whole units for JPY/KRW/VND. `HK$1.23 → --value 123`, `¥100 → --value 100`. The CLI defaults `--currency` to `USD` for revenue events and to `""` for activity events; pass `--currency` explicitly to override. The MCR API converts the value to USD using FX at the event timestamp. | Flag | Required | Meaning | | :--------------- | :---------- | :--------------------------------------------------------------------------------------------------------------- | | `--machine-id` | yes | Positive integer machine ID. | | `--type` | yes | `revenue` or `activity`. | | `--value` | yes | Non-negative integer in the currency's minor unit. | | `--ts` | yes | Unix seconds or ISO 8601 with timezone (`Z` or `+hh:mm`). Must be on or before block time. | | `--currency` | no | ISO 4217 code, 3-10 uppercase alphanumerics (`^[A-Z0-9]{3,10}$`). Default: `USD` for revenue, `""` for activity. | | `--trust` | no | `self` (default), `onchain`, or `hardware`. | | `--source-chain` | no | `same` (default), `peaq`, or `base`. | | `--source-tx` | conditional | 32-byte hex tx hash. **Required** when `--trust onchain`. | | `--raw-data` | no | Path to a file; bytes are hashed and stored as the event data hash. | | `--metadata` | no | Path to a file; bytes are attached as on-chain metadata. Absent = empty bytes. | Human output on success: ``` Event submitted. Machine ID: 42 Type: revenue Value: 123 Trust: self-reported Tx: 0x3f4a8c1e2d9b7f05a6c3e8d1f4b2a7c9e0d5f3b1a8e2c6d9f7b4a1e3c5d8f2b4 Data Hash: 0xa1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890 ``` ### `peaqos qualify mcr` Fetch a machine's credit rating from the [MCR API](/peaqos/api-reference/get-mcr). Wraps [`query_mcr`](/peaqos/sdk-reference/sdk-python#query_mcr). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos qualify mcr did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5 peaqos qualify mcr did:peaq:0x9a5F... --json ``` The DID must match `did:peaq:0x` plus 40 hex characters. `--json` emits the raw SDK response on stdout with no banner or prose: useful for `jq` and scripting. Human output: ``` MCR for did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5 Rating: A Score: 82 / 100 Bond Status: bonded Events: Total: 150 Revenue: 120 Activity: 30 30-Day Revenue: up Last Updated: 2026-04-20T14:30:00Z FX Degraded: no ``` `revenue_trend` is one of `up`, `stable`, `down`, or `insufficient` (returned when there isn't enough revenue history to compute a trend). `FX Degraded:` reflects the top-level `mcr_degraded` field — `yes` when one or more scored events used a stale or unavailable FX snapshot, `no` otherwise. `--json` output (raw SDK `MCRResponse`): ```json theme={"theme":{"light":"github-light-default","dark":"github-dark"}} { "did": "did:peaq:0x9a5F1E244c15e491Ae571c5bF77fDD836ddc37C5", "machine_id": 42, "mcr_score": 82, "mcr": "A", "mcr_degraded": false, "bond_status": "bonded", "negative_flag": false, "event_count": 150, "revenue_event_count": 120, "activity_event_count": 30, "revenue_trend": "up", "total_revenue": 1542075, "average_revenue_per_event": 12851, "last_updated": 1745152200 } ``` ### `peaqos show machine` Fetch a full machine profile: Machine ID, operator, DID attributes, MCR snapshot, recent events. Wraps [`query_machine`](/peaqos/sdk-reference/sdk-python#query_machine). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos show machine did:peaq:0xabc1230000000000000000000000000000000001 peaqos show machine did:peaq:0xabc... --json ``` ### `peaqos show operator machines` List the machines registered under a proxy operator, with MCR per machine. Wraps [`query_operator_machines`](/peaqos/sdk-reference/sdk-python#query_operator_machines). ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark"}} peaqos show operator machines did:peaq:0xProxyAddress peaqos show operator machines did:peaq:0xProxyAddress --json ``` ### `peaqos wallet` Manage OWS-format wallets in the local encrypted vault at `~/.ows/wallets/`. Requires the `[ows]` extra: `pip install peaq-os-cli[ows]`. The vault passphrase is read from `OWS_PASSPHRASE` when set, otherwise prompted interactively. Subcommands wrap the SDK static helpers documented on [Wallets (OWS)](/peaqos/wallets). | Subcommand | Purpose | | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `peaqos wallet create [--words 12\|24] [--json]` | Generate a new BIP-39 mnemonic and derive accounts for every supported chain. The mnemonic is not displayed; back up via `wallet export`. | | `peaqos wallet import --mnemonic [--index N] [--json]` | Import from an existing BIP-39 mnemonic (hidden prompt). `--index` selects the derivation index (default `0`). | | `peaqos wallet import --private-key-file [--json]` | Import a raw EVM private key from file. peaq-only; other chains synthesize on read where possible. | | `peaqos wallet list [--json]` | Compact table of all wallets: Name, ID, peaq Address, Key Type, Created. | | `peaqos wallet show [--json]` | Wallet metadata plus the full multi-chain address table. | | `peaqos wallet export ` | Reveal the recovery phrase / private key. Requires interactive confirmation. Secret prints to stdout; warning prints to stderr. | | `peaqos wallet delete ` | Securely delete a wallet (file overwritten with random bytes before unlink). Requires confirmation. | | `peaqos wallet use ` | Set the active wallet. Writes `PEAQOS_OWS_WALLET=` into `.env` in the current directory. Subsequent commands that call `load_client()` will sign with this wallet. | When `PEAQOS_OWS_WALLET` is set, `load_client()` resolves the wallet from the vault using `OWS_PASSPHRASE` and skips `PEAQOS_PRIVATE_KEY` entirely. If both are set, the wallet wins. ## Exit codes Every subcommand funnels SDK and network exceptions through a single error handler that raises with a stable exit code. | Exit code | Meaning | | :-------- | :----------------------------------------------------------------- | | `0` | Success | | `1` | User / validation error (bad flag, invalid DID, cap or rate limit) | | `2` | Network, RPC, or on-chain error (connection failure, HTTP, revert) | | `3` | Configuration error (missing env var, invalid private key file) | ## See also The peaqOS agent skill that drives these CLI flows from any AI agent. The TypeScript / Python API the CLI wraps. The MCR API that `get-mcr`, `get machine`, and `operator machines` hit.