cloud retention¶

NAME¶

phyware cloud retention — manage a PhyCloud tenant's data retention policy.

SYNOPSIS¶

phyware cloud retention get            [OPTIONS] [--tenant <TENANT_ID>]
phyware cloud retention set            [OPTIONS] --tenant <TENANT_ID> --hot-retention <AGE> --action <ACTION>
phyware cloud retention confirm        [OPTIONS] --tenant <TENANT_ID>
phyware cloud retention cancel         [OPTIONS] --tenant <TENANT_ID>
phyware cloud retention remove         [OPTIONS] --tenant <TENANT_ID>
phyware cloud retention run            [OPTIONS] --tenant <TENANT_ID> [--dry-run]
phyware cloud retention runs           [OPTIONS] --tenant <TENANT_ID> [--limit <N>]
phyware cloud retention verify-archive [OPTIONS] [--tenant <TENANT_ID>]

DESCRIPTION¶

A retention policy says how long a tenant's events stay in the PhyCloud hot store and what happens when they age out: delete erases them, archive-then-delete writes them to the tenant's data lake, verifies them, and only then removes them. A tenant without a policy keeps every event.

get¶

Shows the active policy and any staged change. Without --tenant, shows your own tenant (events:read). Lake credentials are never shown.

set¶

Sets the policy. A change that would make the next run delete more data is staged: it takes effect after a delay (72 hours by default) or when you run confirm. Other changes apply at once.

confirm / cancel¶

Apply or drop a staged change.

remove¶

Removes the policy, so the tenant keeps everything from now on.

run¶

Runs the policy now. With --dry-run, reports what would happen without changing anything.

runs¶

Lists past runs, newest first.

verify-archive¶

Verifies the tenant's hash chain end to end: every archived segment in the lake, then the hot store. Exits with code 1 if verification fails.

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	Applies to	Description
`--tenant`	string	See SYNOPSIS	all	Tenant ID. Needs `admin:tenants`.
`--hot-retention`	string	Yes	`set`	Maximum event age, e.g. `30d`, `12h`. Minimum `1h`.
`--action`	enum	Yes	`set`	`delete` or `archive-then-delete`.
`--max-events`	integer	No	`set`	Keep at most this many events.
`--max-bytes`	integer	No	`set`	Keep at most this many payload bytes.
`--lake`	string	No	`set`	Lake config as JSON, or `@file`. Required for `archive-then-delete`.
`--dry-run`	bool	No	`run`	Report without changing anything.
`--limit`	integer	No	`runs`	Maximum runs to show (default 20).

INPUT¶

--lake takes a JSON object. An S3-compatible lake:

{
  "kind": "s3",
  "bucket": "acme-telemetry",
  "prefix": "phycloud",
  "region": "us-east-1",
  "endpoint": "https://s3.us-east-1.amazonaws.com",
  "credentials": { "access_key_id": "AKIA...", "secret_access_key": "..." }
}

A filesystem lake, relative to the server's PHYCLOUD_LAKE_FS_ROOT:

{ "kind": "filesystem", "path": "acme" }

OUTPUT¶

run and runs return run records:

Field	Type	Description
`status`	string	`completed`, `dry_run`, `paused`, `held`, `no_policy`, `policy_applied`, `failed`
`from_sequence`	integer	First sequence number retired
`to_sequence`	integer	Last sequence number retired
`event_count`	integer	Events deleted
`byte_count`	integer	Payload bytes deleted
`retained_by_hold`	integer	Events kept by a source legal hold
`error`	string	Why a run paused or failed

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¶

# See your own tenant's policy
phyware cloud retention get

# Delete events after 30 days (staged; confirm to apply now)
phyware cloud retention set --tenant acme --hot-retention 30d --action delete
phyware cloud retention confirm --tenant acme

# Archive to S3 after 7 days
phyware cloud retention set --tenant acme --hot-retention 7d \
  --action archive-then-delete --lake @lake.json

# See what a run would do, then run it
phyware cloud retention run --tenant acme --dry-run
phyware cloud retention run --tenant acme

# Verify the full chain across the lake and the hot store
phyware cloud retention verify-archive --tenant acme

AGENT NOTES¶

Always run retention run --dry-run before confirming a new policy. A paused run means the lake failed and nothing more was deleted; read error, fix the lake, and run again. set returns status: pending when a change was staged. verify-archive reads every archived segment, so it can be slow.

ERRORS¶

Code	Message	Remediation
`FORBIDDEN`	Insufficient scope	Use a key with `admin:tenants`
`NOT_FOUND`	Tenant not found / nothing pending	Check `--tenant`
`VALIDATION`	Invalid policy	Check the duration, action and lake
`CONFLICT`	A run is already in progress	Wait and retry