plexsphere

Appearance

plexctl approval ​

Synopsis ​

plexctl approval is the operator surface for the Approval aggregate. It inspects the proposals raised against a Domain's dual-control policy and drives each one through its decision transitions. The token stays singular (approval) because every leaf operates on a single Approval identified by <id>, mirroring plexctl credential get <id>.

The family spans two /v1 surfaces under a single cobra parent:

  • Read — /v1/approvals (list) and /v1/approvals/{id} (get) page the proposals visible to the caller and fetch a single Approval by identifier.
  • Decision — /v1/approvals/{id}/{approve,reject,break-glass} advance a single proposal to a terminal state. approve and reject record an operator decision; break-glass is the audited emergency override that short-circuits the wait for a quorum.

A caller may never approve a proposal they themselves raised; the server enforces the dual-control invariant and surfaces a violation as a 4xx the CLI maps onto its exit-code taxonomy.

text
plexctl approval <subcommand> [flags]

Subcommands ​

plexctl approval list ​

GETs /v1/approvals. Returns the proposals visible to the caller. --status applies an optional lifecycle filter and is validated client-side against the known Approval states before the call leaves the CLI — an unknown value exits 2. --domain-id applies an optional residency filter and is parsed as a UUID locally. Pagination is keyset-based via --cursor / --limit; the response carries a next_cursor the caller threads into the next --cursor to walk the pages.

plexctl approval get <id> ​

GETs /v1/approvals/{id}. Local UUID validation rejects a malformed id with exit 2.

plexctl approval approve <id> ​

POSTs /v1/approvals/{id}/approve. Records the caller's accept decision against the proposal and renders the hydrated Approval (typically in its approved terminal state, or still pending-approval when a further quorum decision is outstanding). The server rejects an attempt to approve a self-raised proposal.

plexctl approval reject <id> ​

POSTs /v1/approvals/{id}/reject with a --reason body. Records the caller's decline decision and renders the hydrated Approval in its rejected terminal state. The --reason flag is required.

plexctl approval break-glass <id> ​

POSTs /v1/approvals/{id}/break-glass with a --reason body. This is the emergency override that force-approves the proposal and short-circuits the wait for a quorum; the justification is audited. The --reason flag is required.

The CLI does not validate the justification length locally. The server owns the minimum-length rule, so a too-short justification surfaces as a 400 the CLI maps onto its exit-code taxonomy. Keeping the bound server-authoritative means the CLI does not drift when the bound changes.

Flags ​

plexctl approval list ​

FlagTypeRequiredDescription
--statusstringnoLifecycle filter: proposed, pending-approval, approved, rejected, or expired. Validated client-side; an unknown value exits 2.
--domain-idUUIDnoOwning Domain UUID to filter by.
--limitintnoMaximum items per page (server default when zero).
--cursorstringnoContinuation token returned by a previous call's next_cursor.

plexctl approval reject <id> ​

FlagTypeRequiredDescription
--reasonstringyesAudit-recorded rejection rationale.

plexctl approval break-glass <id> ​

FlagTypeRequiredDescription
--reasonstringyesAudit-recorded emergency justification. Length is enforced server-side.

plexctl approval get and plexctl approval approve take no subcommand-specific flags beyond the persistent root bag and the positional <id>.

Persistent flags inherited from root ​

--server, --profile, --token-file, --output, --yes. See ../plexctl.md.

Exit codes ​

See ../plexctl.md#exit-code-taxonomy.

Examples ​

List the proposals awaiting a decision ​

shell
plexctl approval list \
  --server    "${PLEXSPHERE_URL}" \
  --status    pending-approval \
  --domain-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0

Approve a proposal ​

shell
plexctl approval approve 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0 \
  --server "${PLEXSPHERE_URL}"

Reject a proposal with an audited rationale ​

shell
plexctl approval reject 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0 \
  --server "${PLEXSPHERE_URL}" \
  --reason "out of scope for this change window"

Force-approve via the audited emergency override ​

shell
plexctl approval break-glass 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0 \
  --server "${PLEXSPHERE_URL}" \
  --reason "incident bridge: restore production access now"

Cross-references ​