$schema: https://docs.phyware.io/phyware/catalog/v1/catalog-schema.json
cli: phyware
commands:
- agent_notes: Use before generating compliance reports to produce tamper-evidence attestations. Pass --output json for machine consumption. Requires read:events scope.
  arguments: []
  description: Fetches the event hash-chain from PhyCloud and cryptographically verifies that every block is correctly linked to the previous one.
  errors:
  - code: NOT_FOUND
    message: Tenant not found
    remediation: Check --tenant-id
  - code: UNAUTHORIZED
    message: Invalid or missing API key
    remediation: Run phyware auth login
  examples:
  - command: phyware cloud verify
    description: Basic verify using env vars
  - command: phyware cloud verify --tenant-id ten_abc123
    description: Verify a specific tenant
  - command: phyware cloud verify --output json
    description: Output as JSON
  - command: phyware cloud verify --from 2024-01-01 --to 2024-01-31
    description: Verify a date range
  - command: phyware cloud verify --url https://cloud.phyware.io --api-key phk_live_abc
    description: Verify against a custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud verify
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: null
    description: Start date (ISO 8601)
    env: null
    flag: --from
    required: false
    type: string
  - default: null
    description: End date (ISO 8601)
    env: null
    flag: --to
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud events list
  - phyware comp evaluate
  synopsis: Verify the hash-chain integrity of a PhyCloud dataset.
- agent_notes: For bulk ingestion prefer events batch. Requires write:events scope. Returns event_id — capture for audit trails.
  arguments: []
  description: Appends a JSON event to the hash-chain for the specified source. Returns the assigned event ID.
  errors:
  - code: INVALID_JSON
    message: Payload is not valid JSON
    remediation: Fix the JSON payload
  - code: NOT_FOUND
    message: Source not found
    remediation: Check --source-id
  examples:
  - command: phyware cloud events send --source-id src_xyz --payload '{"temperature":22.5}'
    description: Send a minimal event
  - command: phyware cloud events send --source-id src_xyz --payload "$(cat event.json)"
    description: Send from a file
  - command: EID=$(phyware cloud events send --source-id src_xyz --payload '{}' -o json | jq -r '.event_id')
    description: Capture event ID
  - command: phyware cloud events send --url https://cloud.phyware.io --source-id src_xyz --payload '{}'
    description: Send to a custom instance
  - command: phyware cloud events send --api-key phk_live_abc --source-id src_xyz --payload '{}'
    description: Send with explicit API key
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud events send
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Source identifier
    env: null
    flag: --source-id
    required: true
    type: string
  - default: null
    description: JSON event payload
    env: null
    flag: --payload
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware cloud events batch
  - phyware cloud sources list
  synopsis: Ingest a single structured event into the PhyCloud ledger.
- agent_notes: Preferred over repeated send calls for bulk ingestion. Requires write:events scope.
  arguments: []
  description: Ingests multiple events from a newline-delimited JSON file. Each line must be a valid JSON object.
  errors:
  - code: INVALID_JSON
    message: A line in the file is not valid JSON
    remediation: Validate NDJSON file before ingesting
  examples:
  - command: phyware cloud events batch --source-id src_xyz --file events.ndjson
    description: Batch ingest from file
  - command: phyware cloud events batch --source-id src_xyz --file events.ndjson --output json
    description: Batch ingest with JSON output
  - command: phyware cloud events batch --url https://cloud.phyware.io --source-id src_xyz --file events.ndjson
    description: Batch ingest to a custom instance
  - command: phyware cloud events batch --source-id src_xyz --file events.ndjson -o json | jq '.accepted'
    description: Ingest and count accepted events
  - command: cat events/*.json | phyware cloud events batch --source-id src_xyz --file -
    description: Generate NDJSON and pipe to batch
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud events batch
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Source identifier
    env: null
    flag: --source-id
    required: true
    type: string
  - default: null
    description: Path to NDJSON file
    env: null
    flag: --file
    required: true
    type: path
  output_schema: null
  see_also:
  - phyware cloud events send
  - phyware cloud sources list
  synopsis: Ingest a batch of events from an NDJSON file.
- agent_notes: Paginated — follow cursor until next_cursor is null. Requires read:events scope.
  arguments: []
  description: Returns a paginated list of events. Supports filtering by tenant, source, and date range.
  errors:
  - code: UNAUTHORIZED
    message: Invalid API key
    remediation: Run phyware auth login
  examples:
  - command: phyware cloud events list
    description: List recent events
  - command: phyware cloud events list --limit 100
    description: List with larger page size
  - command: phyware cloud events list --source-id src_xyz
    description: Filter by source
  - command: phyware cloud events list --output json
    description: Output as JSON
  - command: phyware cloud events list -o json | jq '[.events[].id]'
    description: Extract all event IDs
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud events list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Filter by tenant
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: null
    description: Filter by source
    env: null
    flag: --source-id
    required: false
    type: string
  - default: '20'
    description: Page size
    env: null
    flag: --limit
    required: false
    type: integer
  - default: null
    description: Pagination cursor
    env: null
    flag: --cursor
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud events get
  - phyware cloud sources list
  synopsis: List events with optional filters.
- agent_notes: Use to retrieve full event details after ingestion. Requires read:events scope.
  arguments:
  - description: Unique event identifier
    name: EVENT_ID
    required: true
  description: Returns the full event record for the specified event ID.
  errors:
  - code: NOT_FOUND
    message: Event not found
    remediation: Check EVENT_ID
  examples:
  - command: phyware cloud events get evt_abc123
    description: Get a specific event
  - command: phyware cloud events get evt_abc123 --output json
    description: Get as JSON
  - command: phyware cloud events get evt_abc123 --output yaml
    description: Get as YAML
  - command: phyware cloud events get evt_abc123 -o json | jq '.event.payload'
    description: Extract a field
  - command: phyware cloud events get evt_abc123 --url https://cloud.phyware.io
    description: Get from custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud events get
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud events list
  synopsis: Get a single event by ID.
- agent_notes: Call before events send to confirm source_id. Requires read:sources scope.
  arguments: []
  description: Returns all data sources registered for the active or specified tenant.
  errors:
  - code: UNAUTHORIZED
    message: Invalid API key
    remediation: Run phyware auth login
  examples:
  - command: phyware cloud sources list
    description: List all sources
  - command: phyware cloud sources list --output json
    description: List as JSON
  - command: phyware cloud sources list --tenant-id ten_abc123
    description: List for a specific tenant
  - command: phyware cloud sources list -o json | jq '[.sources[].id]'
    description: Extract source IDs
  - command: phyware cloud sources list --output tsv | wc -l
    description: Count sources
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud sources list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Filter by tenant
    env: null
    flag: --tenant-id
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud sources get
  - phyware cloud events send
  synopsis: List registered data sources.
- agent_notes: Inspect source.schema before constructing event payloads. Requires read:sources scope.
  arguments:
  - description: Unique source identifier
    name: SOURCE_ID
    required: true
  description: Returns the full descriptor for a single source including schema and statistics.
  errors:
  - code: NOT_FOUND
    message: Source not found
    remediation: Check SOURCE_ID
  examples:
  - command: phyware cloud sources get src_xyz
    description: Get a source
  - command: phyware cloud sources get src_xyz --output json
    description: Get as JSON
  - command: phyware cloud sources get src_xyz --output yaml
    description: Get as YAML
  - command: phyware cloud sources get src_xyz -o json | jq '.source.schema'
    description: Extract the event schema
  - command: phyware cloud sources get src_xyz --url https://cloud.phyware.io
    description: Get from custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud sources get
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud sources list
  synopsis: Get a specific registered data source.
- agent_notes: Returns tenant.id — capture for subsequent keys create and events send calls. Requires admin:tenants scope.
  arguments: []
  description: Provisions a new tenant in PhyCloud. Returns the tenant ID.
  errors:
  - code: CONFLICT
    message: Tenant name already exists
    remediation: Choose a different name
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:tenants scope
  examples:
  - command: phyware cloud tenants create --name "Acme Corp"
    description: Create a tenant
  - command: phyware cloud tenants create --name "Big Co" --plan enterprise
    description: Create with enterprise plan
  - command: TID=$(phyware cloud tenants create --name "Test" -o json | jq -r '.tenant.id')
    description: Capture tenant ID
  - command: phyware cloud tenants create --name "Acme" && phyware cloud keys create --name ingest-key
    description: Create and mint a key
  - command: phyware cloud tenants create --name "Acme" --url https://cloud.phyware.io
    description: Create on a custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud tenants create
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant name
    env: null
    flag: --name
    required: true
    type: string
  - default: free
    description: Billing plan
    env: null
    flag: --plan
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud keys create
  - phyware cloud tenants list
  synopsis: Create a new tenant.
- agent_notes: Requires admin:tenants scope. Use --output json for machine consumption.
  arguments: []
  description: Returns all tenants in the installation. Requires admin:tenants scope.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:tenants scope
  examples:
  - command: phyware cloud tenants list
    description: List all tenants
  - command: phyware cloud tenants list --output json
    description: List as JSON
  - command: phyware cloud tenants list -o json | jq '[.tenants[].id]'
    description: Extract tenant IDs
  - command: phyware cloud tenants list --output tsv
    description: List as TSV
  - command: phyware cloud tenants list --output tsv | wc -l
    description: Count tenants
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud tenants list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud tenants get
  - phyware cloud tenants create
  synopsis: List all tenants.
- agent_notes: Requires admin:tenants scope.
  arguments:
  - description: Unique tenant identifier
    name: TENANT_ID
    required: true
  description: Returns full details for a single tenant.
  errors:
  - code: NOT_FOUND
    message: Tenant not found
    remediation: Check TENANT_ID
  examples:
  - command: phyware cloud tenants get ten_abc123
    description: Get a tenant
  - command: phyware cloud tenants get ten_abc123 --output json
    description: Get as JSON
  - command: phyware cloud tenants get ten_abc123 --output yaml
    description: Get as YAML
  - command: phyware cloud tenants get ten_abc123 -o json | jq '.tenant.status'
    description: Check status
  - command: phyware cloud tenants get ten_abc123 --url https://cloud.phyware.io
    description: Get from custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud tenants get
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud tenants list
  synopsis: Get a tenant by ID.
- agent_notes: Irreversible via CLI. Requires admin:tenants scope.
  arguments:
  - description: Unique tenant identifier
    name: TENANT_ID
    required: true
  description: Soft-deletes a tenant. Deactivated tenants cannot ingest new events.
  errors:
  - code: NOT_FOUND
    message: Tenant not found
    remediation: Check TENANT_ID
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:tenants scope
  examples:
  - command: phyware cloud tenants deactivate ten_abc123
    description: Deactivate a tenant
  - command: phyware cloud tenants deactivate ten_abc123 && echo deactivated
    description: Deactivate and confirm
  - command: phyware cloud tenants deactivate ten_abc123 --output json
    description: Deactivate with JSON output
  - command: phyware cloud tenants deactivate ten_abc123 --url https://cloud.phyware.io
    description: Deactivate on custom instance
  - command: phyware cloud tenants get ten_abc123 -o json | jq '.tenant.status'
    description: Verify deactivation
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud tenants deactivate
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud tenants list
  synopsis: Deactivate a tenant.
- agent_notes: Secret shown only once — store immediately. Requires admin:keys scope. Follow least-privilege principles with --scopes.
  arguments: []
  description: Mints a new API key scoped to a tenant. The secret is shown only once.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:keys scope
  - code: CONFLICT
    message: Key name taken
    remediation: Choose a different name
  examples:
  - command: phyware cloud keys create --tenant-id ten_abc123 --name ingest-key
    description: Create a key
  - command: SECRET=$(phyware cloud keys create --tenant-id ten_abc123 --name ci-key -o json | jq -r '.key.secret')
    description: Capture the secret
  - command: phyware cloud keys create --tenant-id ten_abc123 --name read-only --scopes "read:events"
    description: Create with specific scopes
  - command: phyware cloud keys create --tenant-id ten_abc123 --name temp-key --expires 90d
    description: Create with expiry
  - command: phyware cloud keys create --url https://cloud.phyware.io --tenant-id ten_abc123 --name prod-key
    description: Create on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud keys create
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: true
    type: string
  - default: null
    description: Key name
    env: null
    flag: --name
    required: true
    type: string
  - default: read:events write:events
    description: Space-separated OAuth scopes
    env: null
    flag: --scopes
    required: false
    type: string
  - default: null
    description: Expiry duration (e.g. 90d)
    env: null
    flag: --expires
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud keys list
  - phyware cloud tenants create
  synopsis: Create an API key for a tenant.
- agent_notes: Requires admin:keys scope. Secrets are masked in output.
  arguments: []
  description: Lists all API keys for a tenant. Secrets are masked.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:keys scope
  examples:
  - command: phyware cloud keys list --tenant-id ten_abc123
    description: List keys
  - command: phyware cloud keys list --tenant-id ten_abc123 --output json
    description: List as JSON
  - command: phyware cloud keys list --tenant-id ten_abc123 -o json | jq '[.keys[].id]'
    description: Extract key IDs
  - command: phyware cloud keys list --tenant-id ten_abc123 --output tsv | wc -l
    description: Count keys
  - command: phyware cloud keys list --url https://cloud.phyware.io --tenant-id ten_abc123
    description: List on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud keys list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware cloud keys create
  - phyware cloud keys revoke
  synopsis: List API keys for a tenant.
- agent_notes: Revocation is immediate and permanent. Requires admin:keys scope.
  arguments:
  - description: Unique key identifier
    name: KEY_ID
    required: true
  description: Permanently invalidates an API key.
  errors:
  - code: NOT_FOUND
    message: Key not found
    remediation: Check KEY_ID
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:keys scope
  examples:
  - command: phyware cloud keys revoke key_abc123
    description: Revoke a key
  - command: phyware cloud keys revoke key_abc123 && echo revoked
    description: Revoke and confirm
  - command: phyware cloud keys revoke key_abc123 --output json
    description: Revoke with JSON output
  - command: phyware cloud keys revoke key_abc123 --url https://cloud.phyware.io
    description: Revoke on custom instance
  - command: phyware cloud keys list --tenant-id ten_abc123 -o json | jq -r '[.keys[] | select(.expired == true) | .id][]' | xargs -I{} phyware cloud keys revoke {}
    description: List then revoke all expired keys
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud keys revoke
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud keys list
  synopsis: Revoke an API key.
- agent_notes: JWT secret shown only once. Requires admin:tenants scope.
  arguments: []
  description: Issues a new PhyTrace JWT license for a tenant.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:tenants scope
  examples:
  - command: phyware cloud licenses issue --tenant-id ten_abc123
    description: Issue a license
  - command: phyware cloud licenses issue --tenant-id ten_abc123 --ttl 90d
    description: Issue with custom TTL
  - command: JWT=$(phyware cloud licenses issue --tenant-id ten_abc123 -o json | jq -r '.license.token')
    description: Capture the JWT
  - command: phyware cloud licenses issue --tenant-id ten_abc123 && phyware cloud licenses validate --token "$JWT"
    description: Issue and validate
  - command: phyware cloud licenses issue --url https://cloud.phyware.io --tenant-id ten_abc123
    description: Issue on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud licenses issue
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: true
    type: string
  - default: 365d
    description: License TTL
    env: null
    flag: --ttl
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud licenses validate
  - phyware cloud licenses revoke
  synopsis: Issue a PhyTrace license for a tenant.
- agent_notes: Requires admin:tenants scope.
  arguments: []
  description: Lists all licenses with optional filters.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:tenants scope
  examples:
  - command: phyware cloud licenses list
    description: List all licenses
  - command: phyware cloud licenses list --output json
    description: List as JSON
  - command: phyware cloud licenses list -o json | jq '[.licenses[].id]'
    description: Extract license IDs
  - command: phyware cloud licenses list --output tsv | wc -l
    description: Count licenses
  - command: phyware cloud licenses list -o json | jq '[.licenses[] | select(.status == "active")]'
    description: Find active licenses
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud licenses list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud licenses issue
  - phyware cloud licenses revoke
  synopsis: List licenses.
- agent_notes: Revocation is immediate. Requires admin:tenants scope.
  arguments:
  - description: Unique license identifier
    name: LICENSE_ID
    required: true
  description: Revokes a license by ID. Subsequent validations of the JWT will fail.
  errors:
  - code: NOT_FOUND
    message: License not found
    remediation: Check LICENSE_ID
  examples:
  - command: phyware cloud licenses revoke lic_abc123
    description: Revoke a license
  - command: phyware cloud licenses revoke lic_abc123 && echo revoked
    description: Revoke and confirm
  - command: phyware cloud licenses revoke lic_abc123 --output json
    description: Revoke with JSON output
  - command: phyware cloud licenses revoke lic_abc123 --url https://cloud.phyware.io
    description: Revoke on custom instance
  - command: phyware cloud licenses list -o json | jq -r '[.licenses[] | select(.status == "expired") | .id][]' | xargs -I{} phyware cloud licenses revoke {}
    description: List and revoke all expired licenses
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud licenses revoke
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud licenses list
  - phyware cloud licenses validate
  synopsis: Revoke a license.
- agent_notes: No special scope required. Use before distributing a license to confirm it is not expired or revoked.
  arguments: []
  description: Checks signature, expiry, and revocation status of a license JWT.
  errors:
  - code: INVALID_TOKEN
    message: JWT is malformed
    remediation: Ensure the full JWT is passed
  - code: EXPIRED
    message: License has expired
    remediation: Issue a new license
  examples:
  - command: phyware cloud licenses validate --token "$LICENSE_JWT"
    description: Validate a JWT
  - command: phyware cloud licenses validate --token "$LICENSE_JWT" -o json | jq '.valid'
    description: Validate and check result
  - command: phyware cloud licenses validate --token "$(cat license.jwt)"
    description: Validate from a file
  - command: phyware cloud licenses validate --url https://cloud.phyware.io --token "$JWT"
    description: Validate on custom instance
  - command: phyware cloud licenses validate --token "$PHYTRACE_LICENSE" || exit 2
    description: Validate in CI script
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud licenses validate
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: License JWT to validate
    env: null
    flag: --token
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware cloud licenses issue
  - phyware cloud licenses revoke
  synopsis: Validate a license JWT.
- agent_notes: Run status before init to avoid redundant bootstraps. No API key needed for first bootstrap.
  arguments: []
  description: Creates the default admin tenant, admin user, and seed API keys. Idempotent.
  errors:
  - code: ALREADY_DONE
    message: Already bootstrapped
    remediation: Use --force to re-run
  examples:
  - command: phyware cloud bootstrap init
    description: Bootstrap using env vars
  - command: phyware cloud bootstrap init --admin-email admin@example.com
    description: Bootstrap with admin email
  - command: phyware cloud bootstrap init --force
    description: Force re-bootstrap
  - command: phyware cloud bootstrap init --url https://cloud.phyware.io
    description: Bootstrap a custom instance
  - command: phyware cloud bootstrap init && phyware cloud bootstrap status
    description: Bootstrap and check status
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud bootstrap init
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Admin email address
    env: null
    flag: --admin-email
    required: false
    type: string
  - default: 'false'
    description: Force re-bootstrap
    env: null
    flag: --force
    required: false
    type: bool
  output_schema: null
  see_also:
  - phyware cloud bootstrap status
  - phyware comp bootstrap init
  synopsis: Bootstrap the PhyCloud platform.
- agent_notes: No API key required. Use in CI/CD health checks.
  arguments: []
  description: Reports whether the platform has been bootstrapped and all services are healthy.
  errors:
  - code: SERVER_ERROR
    message: PhyCloud unreachable
    remediation: Check service health
  examples:
  - command: phyware cloud bootstrap status
    description: Check status
  - command: phyware cloud bootstrap status --output json
    description: Check as JSON
  - command: phyware cloud bootstrap status -o json | jq '.healthy'
    description: Check health flag
  - command: phyware cloud bootstrap status --url https://cloud.phyware.io
    description: Check on custom instance
  - command: phyware cloud bootstrap status || phyware cloud bootstrap init
    description: Assert bootstrapped in CI
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud bootstrap status
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud bootstrap init
  synopsis: Check PhyCloud bootstrap status.
- agent_notes: Requires read:rules scope. Use before comp evaluate to confirm rules are loaded.
  arguments: []
  description: Lists all compliance rules registered for the active tenant.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure read:rules scope
  examples:
  - command: phyware comp rules list
    description: List all rules
  - command: phyware comp rules list --output json
    description: List as JSON
  - command: phyware comp rules list --category gdpr
    description: Filter by category
  - command: phyware comp rules list -o json | jq '[.rules[].id]'
    description: Extract rule IDs
  - command: phyware comp rules list --output tsv | wc -l
    description: Count rules
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: comp
  input_schema: null
  name: phyware comp rules list
  options:
  - default: http://localhost:8001
    description: PhyComp API base URL
    env: PHYCOMP_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyComp API key
    env: PHYCOMP_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Filter by tenant
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: null
    description: Filter by category
    env: null
    flag: --category
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware comp rules load-defaults
  - phyware comp evaluate
  synopsis: List compliance rules.
- agent_notes: Run once after comp register. Idempotent. Requires write:rules scope.
  arguments: []
  description: Loads ISO 27001, SOC 2, and GDPR relevant checks into the tenant rule catalogue. Idempotent.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure write:rules scope
  examples:
  - command: phyware comp rules load-defaults
    description: Load defaults
  - command: phyware comp rules load-defaults --tenant-id ten_abc123
    description: Load for a specific tenant
  - command: phyware comp rules load-defaults && phyware comp rules list
    description: Load and then list
  - command: phyware comp rules load-defaults --url https://comp.phyware.io
    description: Load on custom instance
  - command: phyware comp rules load-defaults --output json
    description: Load as JSON
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: comp
  input_schema: null
  name: phyware comp rules load-defaults
  options:
  - default: http://localhost:8001
    description: PhyComp API base URL
    env: PHYCOMP_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyComp API key
    env: PHYCOMP_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Target tenant
    env: null
    flag: --tenant-id
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware comp register
  - phyware comp rules list
  synopsis: Load industry-standard default compliance rules.
- agent_notes: Poll after comp evaluate to check for new findings. Requires read:violations scope.
  arguments: []
  description: Returns violations detected during compliance evaluations.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure read:violations scope
  examples:
  - command: phyware comp violations list
    description: List all violations
  - command: phyware comp violations list --severity critical
    description: List critical violations
  - command: phyware comp violations list --output json
    description: List as JSON
  - command: phyware comp violations list --from 2024-01-01 --to 2024-01-31
    description: Filter by date range
  - command: phyware comp violations list --output tsv | wc -l
    description: Count open violations
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: comp
  input_schema: null
  name: phyware comp violations list
  options:
  - default: http://localhost:8001
    description: PhyComp API base URL
    env: PHYCOMP_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyComp API key
    env: PHYCOMP_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Filter by tenant
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: null
    description: Filter by severity
    env: null
    flag: --severity
    required: false
    type: enum(critical|high|medium|low)
  - default: null
    description: Filter by rule
    env: null
    flag: --rule-id
    required: false
    type: string
  - default: null
    description: Start date
    env: null
    flag: --from
    required: false
    type: string
  - default: null
    description: End date
    env: null
    flag: --to
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware comp evaluate
  - phyware comp rules list
  synopsis: List compliance violations.
- agent_notes: Call after batch ingestion. Poll violations list for results. Requires write:evaluations scope.
  arguments: []
  description: Submits an evaluation job to PhyComp which applies all registered rules to event data and records violations.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure write:evaluations scope
  - code: CONFLICT
    message: Evaluation already running
    remediation: Wait for current job to finish
  examples:
  - command: phyware comp evaluate
    description: Evaluate active tenant
  - command: phyware comp evaluate --tenant-id ten_abc123
    description: Evaluate a specific tenant
  - command: phyware comp evaluate --rule-id rule_gdpr_001
    description: Evaluate a single rule
  - command: JOB=$(phyware comp evaluate -o json | jq -r '.job_id')
    description: Capture job ID
  - command: phyware comp evaluate && phyware comp violations list
    description: Evaluate then list violations
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: comp
  input_schema: null
  name: phyware comp evaluate
  options:
  - default: http://localhost:8001
    description: PhyComp API base URL
    env: PHYCOMP_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyComp API key
    env: PHYCOMP_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: null
    description: Evaluate a single rule
    env: null
    flag: --rule-id
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware comp violations list
  - phyware comp rules list
  synopsis: Trigger compliance evaluation for a tenant.
- agent_notes: Run once per tenant. Idempotent. Follow with rules load-defaults. Requires admin:tenants scope.
  arguments: []
  description: Links a PhyCloud tenant to PhyComp, enabling compliance evaluation. Run once per tenant.
  errors:
  - code: CONFLICT
    message: Already registered
    remediation: No action needed
  - code: NOT_FOUND
    message: Tenant not found
    remediation: Create tenant first
  examples:
  - command: phyware comp register
    description: Register using env vars
  - command: phyware comp register --tenant-id ten_abc123
    description: Register a specific tenant
  - command: phyware comp register --phycloud-url https://cloud.phyware.io
    description: Register with explicit PhyCloud URL
  - command: phyware comp register && phyware comp rules load-defaults
    description: Register and load defaults
  - command: phyware comp register --output json
    description: Register with JSON output
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: comp
  input_schema: null
  name: phyware comp register
  options:
  - default: http://localhost:8001
    description: PhyComp API base URL
    env: PHYCOMP_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyComp API key
    env: PHYCOMP_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Tenant identifier
    env: null
    flag: --tenant-id
    required: false
    type: string
  - default: http://localhost:8000
    description: PhyCloud URL
    env: PHYCLOUD_URL
    flag: --phycloud-url
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware comp rules load-defaults
  - phyware comp bootstrap init
  synopsis: Register the active PhyCloud tenant as a PhyComp tenant.
- agent_notes: Creates user in pending status until invitation accepted. Requires admin:users scope.
  arguments: []
  description: Sends an invitation email and creates a pending user record.
  errors:
  - code: CONFLICT
    message: Email already exists
    remediation: User already invited
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:users scope
  examples:
  - command: phyware users invite --email alice@example.com
    description: Invite a user
  - command: phyware users invite --email bob@example.com --role admin
    description: Invite as admin
  - command: phyware users invite --email carol@example.com --output json
    description: Invite with JSON output
  - command: UID=$(phyware users invite --email dave@example.com -o json | jq -r '.user.id')
    description: Capture new user ID
  - command: phyware users invite --url https://cloud.phyware.io --email eve@example.com
    description: Invite on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: users
  input_schema: null
  name: phyware users invite
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: User email address
    env: null
    flag: --email
    required: true
    type: string
  - default: member
    description: User role
    env: null
    flag: --role
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware users list
  - phyware users get
  synopsis: Invite a new user to the tenant.
- agent_notes: Requires admin:users scope.
  arguments: []
  description: Returns all users for the active tenant.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:users scope
  examples:
  - command: phyware users list
    description: List all users
  - command: phyware users list --output json
    description: List as JSON
  - command: phyware users list --output yaml
    description: List as YAML
  - command: phyware users list -o json | jq '[.users[].email]'
    description: Extract user emails
  - command: phyware users list --output tsv | wc -l
    description: Count users
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: users
  input_schema: null
  name: phyware users list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware users get
  - phyware users invite
  synopsis: List all users for the tenant.
- agent_notes: Requires admin:users scope.
  arguments:
  - description: Unique user identifier
    name: USER_ID
    required: true
  description: Returns full details for a single user.
  errors:
  - code: NOT_FOUND
    message: User not found
    remediation: Check USER_ID
  examples:
  - command: phyware users get usr_abc123
    description: Get a user
  - command: phyware users get usr_abc123 --output json
    description: Get as JSON
  - command: phyware users get usr_abc123 --output yaml
    description: Get as YAML
  - command: phyware users get usr_abc123 -o json | jq '.user.status'
    description: Check status
  - command: phyware users get usr_abc123 --url https://cloud.phyware.io
    description: Get on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: users
  input_schema: null
  name: phyware users get
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware users list
  - phyware users deactivate
  synopsis: Get a single user by ID.
- agent_notes: Irreversible via CLI. Requires admin:users scope.
  arguments:
  - description: Unique user identifier
    name: USER_ID
    required: true
  description: Soft-deletes a user, revoking all sessions and API keys.
  errors:
  - code: NOT_FOUND
    message: User not found
    remediation: Check USER_ID
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:users scope
  examples:
  - command: phyware users deactivate usr_abc123
    description: Deactivate a user
  - command: phyware users deactivate usr_abc123 && echo deactivated
    description: Deactivate and confirm
  - command: phyware users deactivate usr_abc123 --output json
    description: Deactivate with JSON output
  - command: phyware users deactivate usr_abc123 --url https://cloud.phyware.io
    description: Deactivate on custom instance
  - command: phyware users list -o json | jq -r '.users[] | select(.email == "old@example.com") | .id' | xargs phyware users deactivate
    description: List then deactivate a user
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: users
  input_schema: null
  name: phyware users deactivate
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware users list
  synopsis: Deactivate a user.
- agent_notes: For CI/CD set PHYCLOUD_API_KEY env var instead. Device-code requires interactive browser session.
  arguments: []
  description: Starts the device-code OAuth flow. Pass --with-token to read a PAT from stdin.
  errors:
  - code: UNAUTHORIZED
    message: Invalid credentials
    remediation: Re-run auth login
  examples:
  - command: phyware auth login --host https://cloud.phyware.io
    description: Device-code login
  - command: echo "$PAT" | phyware auth login --with-token
    description: PAT login via stdin
  - command: phyware auth login --host http://localhost:8000
    description: Login to local instance
  - command: phyware auth login && phyware auth status
    description: Login and check status
  - command: echo "$PHYCLOUD_PAT" | phyware auth login --with-token --host https://cloud.phyware.io
    description: CI login with PAT
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth login
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: API host URL
    env: null
    flag: --host
    required: false
    type: string
  - default: 'false'
    description: Read PAT from stdin
    env: null
    flag: --with-token
    required: false
    type: bool
  output_schema: null
  see_also:
  - phyware auth status
  - phyware auth logout
  synopsis: Authenticate via device-code OAuth or Personal Access Token.
- agent_notes: Revokes server-side token. After logout PHYCLOUD_API_KEY env var is still honoured if set.
  arguments: []
  description: Revokes the current access token and removes credentials from the store.
  errors:
  - code: UNAUTHORIZED
    message: Already logged out
    remediation: No action needed
  examples:
  - command: phyware auth logout
    description: Log out
  - command: phyware auth logout && echo logged-out
    description: Logout and confirm
  - command: phyware auth logout --url https://cloud.phyware.io
    description: Logout from specific host
  - command: phyware auth logout && phyware auth login
    description: Logout and re-login
  - command: phyware auth logout --output json
    description: Logout with JSON output
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth logout
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware auth login
  - phyware auth status
  synopsis: Revoke token and log out.
- agent_notes: Call before any other command to confirm valid credentials. Exit code 2 indicates auth failure.
  arguments: []
  description: Prints the active identity, scopes, token expiry, and host.
  errors:
  - code: UNAUTHORIZED
    message: Not authenticated
    remediation: Run phyware auth login
  examples:
  - command: phyware auth status
    description: Check authentication status
  - command: phyware auth status --output json
    description: Check as JSON
  - command: phyware auth status -o json | jq '.expiry'
    description: Extract expiry
  - command: phyware auth status || exit 2
    description: Assert authenticated in CI
  - command: phyware auth status --url https://cloud.phyware.io
    description: Check on custom host
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth status
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware auth login
  - phyware auth refresh
  synopsis: Show active identity, scopes, and token expiry.
- agent_notes: Prints raw token — do not log. Prefer PHYCLOUD_API_KEY env var for automation.
  arguments: []
  description: Outputs the raw access token to stdout. Useful for injecting into external HTTP calls.
  errors:
  - code: UNAUTHORIZED
    message: Not authenticated
    remediation: Run phyware auth login
  examples:
  - command: phyware auth token
    description: Print token
  - command: 'curl -H "Authorization: Bearer $(phyware auth token)" https://api.example.com'
    description: Use in curl
  - command: TOKEN=$(phyware auth token)
    description: Store in variable
  - command: phyware auth token | cut -d. -f1 | base64 -d 2>/dev/null | jq
    description: Validate token format
  - command: export PHYCLOUD_API_KEY=$(phyware auth token)
    description: Export for sub-processes
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth token
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware auth status
  - phyware auth refresh
  synopsis: Print the current access token.
- agent_notes: Use in long-running jobs to keep tokens valid. Falls back to re-login if refresh token is expired.
  arguments: []
  description: Validates the current token; refreshes it if it is close to expiry.
  errors:
  - code: EXPIRED
    message: Refresh token expired
    remediation: Run phyware auth login again
  examples:
  - command: phyware auth refresh
    description: Refresh token
  - command: phyware auth refresh && phyware auth status
    description: Refresh and check status
  - command: phyware auth refresh --output json
    description: Refresh with JSON output
  - command: phyware auth refresh || phyware auth login --with-token
    description: Refresh in CI cron
  - command: phyware auth refresh --url https://cloud.phyware.io
    description: Refresh on custom host
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth refresh
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware auth status
  - phyware auth login
  synopsis: Validate and refresh the current access token.
- agent_notes: Must have previously authenticated to the target host. Use auth status to confirm after switching.
  arguments: []
  description: Changes the active host in multi-host setups.
  errors:
  - code: NOT_FOUND
    message: No credentials for host
    remediation: Run phyware auth login --host <URL> first
  examples:
  - command: phyware auth switch --host https://cloud.phyware.io
    description: Switch to production
  - command: phyware auth switch --host https://staging.phyware.io
    description: Switch to staging
  - command: phyware auth switch --host http://localhost:8000
    description: Switch to local
  - command: phyware auth switch --host https://cloud.phyware.io && phyware auth status
    description: Switch and verify
  - command: phyware auth switch --host https://cloud.phyware.io --output json
    description: Switch with JSON output
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth switch
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Target host URL
    env: null
    flag: --host
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware auth login
  - phyware auth status
  synopsis: Switch the active host.
- agent_notes: Requires admin:sessions scope for other users. No scope needed for own sessions.
  arguments: []
  description: Returns all active sessions for the specified user.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:sessions scope
  examples:
  - command: phyware auth sessions list
    description: List own sessions
  - command: phyware auth sessions list --user-id usr_abc123
    description: List sessions for a user
  - command: phyware auth sessions list --output json
    description: List as JSON
  - command: phyware auth sessions list -o json | jq '[.sessions[].id]'
    description: Extract session IDs
  - command: phyware auth sessions list --output tsv | wc -l
    description: Count active sessions
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth sessions list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: (self)
    description: User to query
    env: null
    flag: --user-id
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware auth sessions revoke
  - phyware auth logout
  synopsis: List active sessions for a user.
- agent_notes: Requires admin:sessions scope for other users. Immediate effect.
  arguments:
  - description: Unique session identifier
    name: SESSION_ID
    required: true
  description: Immediately invalidates a session by ID.
  errors:
  - code: NOT_FOUND
    message: Session not found
    remediation: Check SESSION_ID
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure admin:sessions scope
  examples:
  - command: phyware auth sessions revoke ses_abc123
    description: Revoke a session
  - command: phyware auth sessions revoke ses_abc123 && echo revoked
    description: Revoke and confirm
  - command: phyware auth sessions revoke ses_abc123 --output json
    description: Revoke with JSON output
  - command: phyware auth sessions list --user-id usr_abc123 -o json | jq -r '[.sessions[].id][]' | xargs -I{} phyware auth sessions revoke {}
    description: Revoke all sessions for a user
  - command: phyware auth sessions revoke ses_abc123 --url https://cloud.phyware.io
    description: Revoke on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: auth
  input_schema: null
  name: phyware auth sessions revoke
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware auth sessions list
  - phyware auth logout
  synopsis: Revoke a session.
- agent_notes: Requires events:read scope. Locker starts in `created` state; use `seal` to copy data.
  arguments: []
  description: Creates a new Evidence Locker entity (status=created). Use `seal` to copy data and compute the Merkle root.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure events:read scope
  - code: VALIDATION
    message: Invalid scope JSON
    remediation: Pass a valid JSON object to --scope
  examples:
  - command: phyware cloud lockers create --name "Incident AGV-042"
    description: Create a basic locker
  - command: phyware cloud lockers create --name "Audit Q1" --scope '{"source_ids":["AGV-042"]}'
    description: Create with scope
  - command: phyware cloud lockers create --name "TTL Locker" --expires-at 2027-01-01T00:00:00Z
    description: Create with expiration
  - command: LK=$(phyware cloud lockers create --name "Auto" -o json | jq -r '.locker_id')
    description: Capture locker ID
  - command: phyware cloud lockers create --name "Incident" --output json
    description: Create as JSON
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers create
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Human-readable locker name
    env: null
    flag: --name
    required: true
    type: string
  - default: null
    description: Optional description / context
    env: null
    flag: --description
    required: false
    type: string
  - default: null
    description: JSON-encoded scope object (time_range, source_ids, event_types)
    env: null
    flag: --scope
    required: false
    type: string
  - default: null
    description: ISO-8601 expiration timestamp
    env: null
    flag: --expires-at
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud lockers seal
  - phyware cloud lockers list
  synopsis: Create a new Evidence Locker.
- agent_notes: 'Idempotent: re-sealing a sealed locker returns the existing root. Requires events:read scope.'
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Copies events matching the locker scope and computes the Merkle root. After sealing the locker is immutable and queryable.
  errors:
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  - code: VALIDATION
    message: Locker cannot be sealed in its current state
    remediation: Ensure the locker is in `created` state
  examples:
  - command: phyware cloud lockers seal lk_abc123
    description: Seal a locker
  - command: phyware cloud lockers seal lk_abc123 -o json | jq -r '.merkle_root'
    description: Seal and capture root
  - command: phyware cloud lockers seal lk_abc123 --output json
    description: Seal as JSON
  - command: phyware cloud lockers seal lk_abc123 --output yaml
    description: Seal as YAML
  - command: phyware cloud lockers seal lk_abc123 --url https://cloud.phyware.io
    description: Seal on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers seal
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud lockers create
  - phyware cloud evidence verify
  synopsis: Seal an Evidence Locker.
- agent_notes: Requires events:read scope. Use --output json for machine consumption.
  arguments: []
  description: Returns a paginated list of all lockers owned by the current tenant.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure events:read scope
  examples:
  - command: phyware cloud lockers list
    description: List all lockers
  - command: phyware cloud lockers list --output json
    description: List as JSON
  - command: phyware cloud lockers list --offset 50 --limit 100
    description: Paginate
  - command: phyware cloud lockers list -o json | jq '[.[] | select(.status == "sealed") | .locker_id]'
    description: Extract sealed locker IDs
  - command: phyware cloud lockers list --output tsv
    description: List as TSV
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: '0'
    description: Pagination offset
    env: null
    flag: --offset
    required: false
    type: integer
  - default: '50'
    description: Max lockers to return (1–200)
    env: null
    flag: --limit
    required: false
    type: integer
  output_schema: null
  see_also:
  - phyware cloud lockers get
  - phyware cloud lockers create
  synopsis: List Evidence Lockers for the current tenant.
- agent_notes: Requires events:read scope and locker must belong to the current tenant.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Returns full details for a single locker including its scope, status, event count, and Merkle root.
  errors:
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  examples:
  - command: phyware cloud lockers get lk_abc123
    description: Get a locker
  - command: phyware cloud lockers get lk_abc123 --output json
    description: Get as JSON
  - command: phyware cloud lockers get lk_abc123 --output yaml
    description: Get as YAML
  - command: phyware cloud lockers get lk_abc123 -o json | jq -r '.status'
    description: Check status
  - command: phyware cloud lockers get lk_abc123 --url https://cloud.phyware.io
    description: Get on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers get
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud lockers list
  synopsis: Get a single Evidence Locker by ID.
- agent_notes: Requires events:write scope. Data is retained, not deleted.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Marks a locker as archived. Locker data is retained per the platform retention policy.
  errors:
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  - code: VALIDATION
    message: Locker already archived
    remediation: Locker is already in archived state
  examples:
  - command: phyware cloud lockers archive lk_abc123
    description: Archive a locker
  - command: phyware cloud lockers archive lk_abc123 && echo archived
    description: Archive and confirm
  - command: phyware cloud lockers archive lk_abc123 --output json
    description: Archive with JSON output
  - command: phyware cloud lockers archive lk_abc123 --url https://cloud.phyware.io
    description: Archive on custom instance
  - command: phyware cloud lockers get lk_abc123 -o json | jq -r '.status'
    description: Verify archived status
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers archive
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud lockers list
  synopsis: Archive an Evidence Locker.
- agent_notes: Requires events:write scope. Access token is shown only once — capture and store immediately.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Issues a scoped, time-limited access token to a stakeholder (regulator, insurer, legal, auditor, etc). The access token is shown only once.
  errors:
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure events:write scope
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  - code: VALIDATION
    message: Invalid stakeholder type
    remediation: 'Use one of: regulator, insurer, legal, auditor, operator'
  examples:
  - command: phyware cloud lockers grants issue lk_abc123 --stakeholder-name "NHTSA Region 5" --stakeholder-type regulator
    description: Issue a regulator grant
  - command: phyware cloud lockers grants issue lk_abc123 --stakeholder-name "Insurer" --stakeholder-type insurer --permissions read_events,read_provenance
    description: Issue with permissions
  - command: phyware cloud lockers grants issue lk_abc123 --stakeholder-name "Auditor" --stakeholder-type auditor --expires-at 2026-12-31T00:00:00Z
    description: Issue with expiry
  - command: TOKEN=$(phyware cloud lockers grants issue lk_abc123 --stakeholder-name "Legal" --stakeholder-type legal -o json | jq -r '.access_token')
    description: Capture access token
  - command: phyware cloud lockers grants issue lk_abc123 --stakeholder-name "Org" --stakeholder-type operator --output json
    description: Issue as JSON
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers grants issue
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Stakeholder organization or individual name
    env: null
    flag: --stakeholder-name
    required: true
    type: string
  - default: null
    description: 'Type: regulator, insurer, legal, auditor, operator'
    env: null
    flag: --stakeholder-type
    required: true
    type: string
  - default: null
    description: External organization identifier
    env: null
    flag: --stakeholder-org-id
    required: false
    type: string
  - default: null
    description: Comma-separated permissions (read_events, read_provenance, …)
    env: null
    flag: --permissions
    required: false
    type: string
  - default: null
    description: ISO-8601 grant expiration timestamp
    env: null
    flag: --expires-at
    required: false
    type: string
  output_schema: null
  see_also:
  - phyware cloud lockers grants list
  - phyware cloud lockers grants revoke
  synopsis: Issue a stakeholder access grant for a locker.
- agent_notes: Requires events:read scope. Access tokens are NOT returned — only grant metadata.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Returns all grants (active and revoked) issued for the locker.
  errors:
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  examples:
  - command: phyware cloud lockers grants list lk_abc123
    description: List grants
  - command: phyware cloud lockers grants list lk_abc123 --output json
    description: List as JSON
  - command: phyware cloud lockers grants list lk_abc123 -o json | jq '[.[] | select(.revoked_at == null)]'
    description: List active grants only
  - command: phyware cloud lockers grants list lk_abc123 -o json | jq '[.[].grant_id]'
    description: Extract grant IDs
  - command: phyware cloud lockers grants list lk_abc123 --output tsv
    description: List as TSV
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers grants list
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud lockers grants issue
  - phyware cloud lockers grants revoke
  synopsis: List access grants for a locker.
- agent_notes: Requires events:write scope. Immediate effect — issued access tokens stop working.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  - description: Grant identifier
    name: GRANT_ID
    required: true
  description: Immediately invalidates the grant's access token. The grant record is retained with a revoked_at timestamp.
  errors:
  - code: NOT_FOUND
    message: Grant not found
    remediation: Check LOCKER_ID and GRANT_ID
  - code: FORBIDDEN
    message: Insufficient scope
    remediation: Ensure events:write scope
  examples:
  - command: phyware cloud lockers grants revoke lk_abc123 gr_def456
    description: Revoke a grant
  - command: phyware cloud lockers grants revoke lk_abc123 gr_def456 && echo revoked
    description: Revoke and confirm
  - command: phyware cloud lockers grants revoke lk_abc123 gr_def456 --output json
    description: Revoke with JSON output
  - command: phyware cloud lockers grants list lk_abc123 -o json | jq -r '.[].grant_id' | xargs -I{} phyware cloud lockers grants revoke lk_abc123 {}
    description: Revoke all grants for a locker
  - command: phyware cloud lockers grants revoke lk_abc123 gr_def456 --url https://cloud.phyware.io
    description: Revoke on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers grants revoke
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  output_schema: null
  see_also:
  - phyware cloud lockers grants list
  synopsis: Revoke a stakeholder access grant.
- agent_notes: Requires events:read scope. Audit log is append-only and tamper-evident.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Returns all access and admin actions on the locker (created, sealed, queried, exported, grant_issued, grant_revoked).
  errors:
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  examples:
  - command: phyware cloud lockers audit-log lk_abc123
    description: View audit log
  - command: phyware cloud lockers audit-log lk_abc123 --output json
    description: View as JSON
  - command: phyware cloud lockers audit-log lk_abc123 --offset 100 --limit 50
    description: Paginate
  - command: phyware cloud lockers audit-log lk_abc123 -o json | jq '[.[] | select(.action == "queried")]'
    description: Filter by action
  - command: phyware cloud lockers audit-log lk_abc123 --output tsv
    description: View as TSV
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud lockers audit-log
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: '0'
    description: Pagination offset
    env: null
    flag: --offset
    required: false
    type: integer
  - default: '100'
    description: Max entries to return (1–500)
    env: null
    flag: --limit
    required: false
    type: integer
  output_schema: null
  see_also:
  - phyware cloud lockers get
  synopsis: View the audit log for a locker.
- agent_notes: Authenticates with a stakeholder grant token (Bearer), NOT a tenant API key. The token is recorded in the locker audit log on every query.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Returns events copied into the locker. Authenticates with a Bearer grant token (issued by the locker operator), not a tenant API key.
  errors:
  - code: FORBIDDEN
    message: Invalid or insufficient grant token
    remediation: Verify the grant token and that it has read_events permission
  examples:
  - command: phyware cloud evidence events lk_abc123 --grant-token $TOKEN
    description: List events with grant token
  - command: PHYCLOUD_GRANT_TOKEN=$TOKEN phyware cloud evidence events lk_abc123
    description: Use env var
  - command: phyware cloud evidence events lk_abc123 --grant-token $TOKEN --output json
    description: Output as JSON
  - command: phyware cloud evidence events lk_abc123 --grant-token $TOKEN --offset 100 --limit 50
    description: Paginate
  - command: phyware cloud evidence events lk_abc123 --grant-token $TOKEN -o json | jq '[.[].content_hash]'
    description: Extract event hashes
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud evidence events
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Stakeholder grant token (Bearer)
    env: PHYCLOUD_GRANT_TOKEN
    flag: --grant-token
    required: true
    type: string
  - default: '0'
    description: Pagination offset
    env: null
    flag: --offset
    required: false
    type: integer
  - default: '100'
    description: Max events to return (1–500)
    env: null
    flag: --limit
    required: false
    type: integer
  output_schema: null
  see_also:
  - phyware cloud evidence manifest
  - phyware cloud evidence verify
  synopsis: 'Stakeholder query: list events in a sealed locker.'
- agent_notes: Lightweight call — returns metadata only, no event payloads. Use before `verify` or `events`.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Returns the locker manifest (scope, event count, Merkle root, sealed timestamp). Authenticates with a Bearer grant token.
  errors:
  - code: FORBIDDEN
    message: Invalid or insufficient grant token
    remediation: Verify the grant token has read_events permission
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  examples:
  - command: phyware cloud evidence manifest lk_abc123 --grant-token $TOKEN
    description: Get manifest
  - command: PHYCLOUD_GRANT_TOKEN=$TOKEN phyware cloud evidence manifest lk_abc123
    description: Use env var
  - command: phyware cloud evidence manifest lk_abc123 --grant-token $TOKEN --output json
    description: Output as JSON
  - command: phyware cloud evidence manifest lk_abc123 --grant-token $TOKEN -o json | jq -r '.merkle_root'
    description: Get Merkle root
  - command: phyware cloud evidence manifest lk_abc123 --grant-token $TOKEN --output yaml
    description: Output as YAML
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud evidence manifest
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Stakeholder grant token (Bearer)
    env: PHYCLOUD_GRANT_TOKEN
    flag: --grant-token
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware cloud evidence verify
  - phyware cloud evidence events
  synopsis: 'Stakeholder query: get the locker manifest.'
- agent_notes: Independently recomputes the Merkle root server-side and compares to the stored value. Use to verify a locker has not been tampered with.
  arguments:
  - description: Unique locker identifier
    name: LOCKER_ID
    required: true
  description: Recomputes the Merkle root from the locker's events and compares it to the sealed value. Authenticates with a Bearer grant token.
  errors:
  - code: FORBIDDEN
    message: Invalid or insufficient grant token
    remediation: Verify the grant token has read_events permission
  - code: NOT_FOUND
    message: Locker not found
    remediation: Check LOCKER_ID
  examples:
  - command: phyware cloud evidence verify lk_abc123 --grant-token $TOKEN
    description: Verify a locker
  - command: PHYCLOUD_GRANT_TOKEN=$TOKEN phyware cloud evidence verify lk_abc123
    description: Use env var
  - command: phyware cloud evidence verify lk_abc123 --grant-token $TOKEN --output json
    description: Output as JSON
  - command: phyware cloud evidence verify lk_abc123 --grant-token $TOKEN -o json | jq -r '.valid'
    description: Check valid flag
  - command: phyware cloud evidence verify lk_abc123 --grant-token $TOKEN --url https://cloud.phyware.io
    description: Verify on custom instance
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: cloud
  input_schema: null
  name: phyware cloud evidence verify
  options:
  - default: http://localhost:8000
    description: PhyCloud API base URL
    env: PHYCLOUD_URL
    flag: --url
    required: false
    type: string
  - default: null
    description: PhyCloud API key
    env: PHYCLOUD_API_KEY
    flag: --api-key
    required: false
    type: string
  - default: table
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(table|json|yaml|tsv)
  - default: null
    description: Stakeholder grant token (Bearer)
    env: PHYCLOUD_GRANT_TOKEN
    flag: --grant-token
    required: true
    type: string
  output_schema: null
  see_also:
  - phyware cloud evidence manifest
  - phyware cloud lockers seal
  synopsis: 'Stakeholder query: verify locker integrity.'
- agent_notes: Primary discovery mechanism for AI agents. No authentication required. Cache at session start.
  arguments: []
  description: Outputs a versioned, structured catalog of all phyware commands including options, schemas, examples, and agent notes.
  errors:
  - code: INTERNAL
    message: Serialization error
    remediation: File a bug report
  examples:
  - command: phyware commands catalog
    description: Emit catalog as JSON
  - command: phyware commands catalog --output yaml
    description: Emit as YAML
  - command: phyware commands catalog --output tsv | cut -f1
    description: List command names only
  - command: phyware commands catalog | jq '[.commands[] | select(.group == "cloud") | .name]'
    description: Extract cloud commands
  - command: phyware commands catalog | jq '[.commands[] | select(.synopsis | contains("event"))]'
    description: Find command by synopsis
  exit_codes:
  - code: 0
    meaning: Success
  - code: 1
    meaning: Generic / connection error
  - code: 2
    meaning: Authentication / authorisation error (HTTP 401/403)
  - code: 3
    meaning: Resource not found (HTTP 404)
  - code: 4
    meaning: Validation error (HTTP 400/422)
  - code: 5
    meaning: Server-side error (HTTP 5xx)
  group: commands
  input_schema: null
  name: phyware commands catalog
  options:
  - default: json
    description: Output format
    env: null
    flag: --output
    required: false
    type: enum(json|yaml|tsv)
  output_schema: null
  see_also: []
  synopsis: Emit a machine-readable catalog of every phyware command.
description: Machine-readable command catalog for phyware CLI.
version: '1'
