cloud devices¶

NAME¶

phyware cloud devices — manage the device registry: keys, hardware binding, attestation state, versions and certificates.

SYNOPSIS¶

phyware cloud devices list
phyware cloud devices get            <DEVICE_ID>
phyware cloud devices challenge
phyware cloud devices revoke         <DEVICE_ID> [--reason TEXT] [--effective-at TIME]
phyware cloud devices rotate-key     <DEVICE_ID> --file FILE
phyware cloud devices register-ak    <DEVICE_ID> --file FILE
phyware cloud devices set-class      <DEVICE_ID> [DEVICE_CLASS]
phyware cloud devices attestation    <DEVICE_ID>
phyware cloud devices versions       <DEVICE_ID>
phyware cloud devices certificates   <DEVICE_ID>
phyware cloud devices decommission   <DEVICE_ID> [--reason TEXT]
phyware cloud devices ca
phyware cloud devices crl
phyware cloud devices cert-status    <SERIAL>
phyware cloud devices factory-eks upload --file FILE
phyware cloud devices factory-eks get    <SERIAL>

DESCRIPTION¶

A device is a robot's signing identity: a key (usually in its TPM) bound to one source_id. See Devices for the model.

list / get: devices with their keys and, once bound to the TPM, the hardware block (EK certificate, device certificate).
challenge: a single-use nonce. The device signs it; the CLI never holds device keys.
rotate-key / register-ak: post a device-signed request (public_key_pem, nonce, proof) produced on the device, from --file (- for stdin).
revoke / decommission: revoke the device, its keys and certificates; decommission also marks it decommissioned (end of life, RMA).
set-class: the class selects attestation reference values and firmware policies.
attestation: trusted, untrusted or unknown, the latest quote and the state history.
versions: agent and TPM firmware versions and boot digests seen.
certificates / ca / crl / cert-status: device certificates, the CA that issues them, its CRL and per-certificate status (ca, crl and cert-status need no credential).
factory-eks: EK certificates captured at manufacture, by device serial; binding a device with that serial must present the same EK.

OPTIONS¶

Flag	Type	Required	Default	Env
`--url`	string	No	`http://localhost:8000`	`PHYCLOUD_URL`
`--api-key`	string	No	—	`PHYCLOUD_API_KEY`
`--output`	enum	No	`table`	—
`--reason`	string	No	—	—
`--effective-at`	string	No	now	—
`--file`	path	Yes (rotate-key, register-ak, factory-eks upload)	—	—

ARGUMENTS¶

Name	Required	Description
`DEVICE_ID`	Yes	Device ID
`DEVICE_CLASS`	No	Class for set-class; omit to clear
`SERIAL`	Yes	Certificate serial (hex) or device serial

EXIT CODES¶

Code	Meaning
`0`	Success
`1`	Generic / connection error
`2`	Authentication / authorisation error
`3`	Resource not found
`4`	Validation error
`5`	Server-side error

EXAMPLES¶

# Devices and their state
phyware cloud devices list
phyware cloud devices attestation 3f2c0a1e-... -o json | jq -r '.state'

# Rotate a key with a request the device signed
phyware cloud devices challenge -o json | jq -r .nonce   # give it to the device
phyware cloud devices rotate-key 3f2c0a1e-... --file rotate.json

# Retire a unit
phyware cloud devices decommission 3f2c0a1e-... --reason "RMA 42"

# Check a device certificate offline
phyware cloud devices ca > ca.pem && phyware cloud devices crl > devices.crl
openssl verify -crl_check -CAfile ca.pem -CRLfile devices.crl device.pem

AGENT NOTES¶

Use --output json and jq. Read commands need devices:read; changes need devices:write. ca, crl and cert-status are public. Never ask the CLI to sign for a device: device keys stay in the device's TPM.

ERRORS¶

Code	Message	Remediation
`NOT_FOUND`	Device not found	Check `DEVICE_ID` with `devices list`
`FORBIDDEN`	Insufficient scope	Use a key with `devices:read` / `devices:write`
`VALIDATION`	Request rejected	Bad nonce, proof or value; read the message