{ "$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 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" }