cloud holds¶

NAME¶

phyware cloud holds — place and release legal holds that block data retention.

SYNOPSIS¶

phyware cloud holds list    [OPTIONS] --tenant <TENANT_ID> [--include-released]
phyware cloud holds create  [OPTIONS] --tenant <TENANT_ID> [--source <SOURCE_ID>] --reason <TEXT>
phyware cloud holds release [OPTIONS] --tenant <TENANT_ID> <HOLD_ID>

DESCRIPTION¶

While a legal hold is active, the retention job deletes none of the events it covers, whatever the tenant's policy says. A hold covers a whole tenant, or one source with --source. Archiving continues, so the lake stays complete.

Releasing a hold keeps its record. The next retention run removes the events the hold was keeping. Under an archive policy it removes only events that were archived.

All commands require the admin:tenants scope and are written to the audit log.

OPTIONS¶

Flag	Type	Required	Default	Env
`--url`	string	No	`http://localhost:8000`	`PHYCLOUD_URL`
`--api-key`	string	No	—	`PHYCLOUD_API_KEY`
`--output`	enum	No	`table`	—

Flag	Type	Required	Description
`--tenant`	string	Yes	Tenant ID
`--source`	string	No (`create`)	Hold only this source
`--reason`	string	Yes (`create`)	Why the hold exists
`--include-released`	bool	No (`list`)	Include released holds

ARGUMENTS¶

Name	Required	Description
`HOLD_ID`	Yes (`release`)	Hold to release

INPUT¶

None.

OUTPUT¶

Field	Type	Description
`hold_id`	string	Hold identifier
`source_id`	string	Held source, or `null` for the whole tenant
`reason`	string	Why the hold exists
`created_at`	string	When it was placed
`released_at`	string	When it was released, or `null`

EXIT CODES¶

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

EXAMPLES¶

# Hold everything for a tenant
phyware cloud holds create --tenant acme --reason "Case 2026-114"

# Hold one robot's data
phyware cloud holds create --tenant acme --source ROBOT-001 --reason "Incident 42"

# List active holds
phyware cloud holds list --tenant acme

# Release a hold
phyware cloud holds release --tenant acme hold_3f9a

# Capture a hold id in a script
HID=$(phyware cloud holds create --tenant acme --reason "Audit" -o json | jq -r '.hold_id')

AGENT NOTES¶

Place a hold before running retention on data that may be needed as evidence. A tenant-level hold stops retention runs entirely (status: held). Evidence lockers are separate: sealed lockers keep their own copy of events and survive retention without a hold.

ERRORS¶

Code	Message	Remediation
`FORBIDDEN`	Insufficient scope	Use a key with `admin:tenants`
`NOT_FOUND`	No active legal hold with that id	Check `HOLD_ID`
`VALIDATION`	reason is required	Pass `--reason`