plexctl policy

Synopsis

plexctl policy is the operator surface for the L3/L4 connectivity Policies of a Project. Every leaf is scoped to a single Project via the required --project-id flag. The family wraps the per-Project Policy /v1 surface under a single cobra parent:

• list / get — page the Policies in a Project and fetch one by id.
• update — patch a Policy, landing a new revision from a YAML document.
• delete — remove a Policy (requires --yes and a recorded --reason).
• revisions list / get — page a Policy's append-only revision history and fetch a single revision.
• diff — show the structural difference between two revisions.
• dry-run — evaluate a candidate revision against the current Project state without writing anything.

plexctl policy <subcommand> [flags]
plexctl policy revisions <subcommand> [flags]

Subcommands

plexctl policy list

GETs /v1/projects/{project_id}/policies. Pagination is keyset-based via --cursor / --limit; the response carries a next_cursor the caller threads into the next --cursor to walk the pages. The text render lists each Policy's id, slug, display name, head revision id, Project id, and last-updated timestamp.

plexctl policy get <policy-id>

GETs /v1/projects/{project_id}/policies/{policy_id}. Local UUID validation rejects a malformed policy-id with exit 2.

plexctl policy update <policy-id>

PATCHes /v1/projects/{project_id}/policies/{policy_id}, landing a new revision. The patch body is read from the --revision-yaml document (a file path, or - to read stdin): the YAML is parsed and round-tripped through JSON so the document's keys map onto the wire schema (display_name, selector, rules, …). The hydrated Policy is rendered on success.

plexctl policy delete <policy-id>

DELETEs /v1/projects/{project_id}/policies/{policy_id}. Requires --yes (refused client-side without it) and a required --reason string. The delete operation has no server-side reason channel today, so the CLI echoes the typed rationale to stderr as the operator's locally recorded reason rather than transmitting it on the wire; stdout stays clean for parsers.

plexctl policy revisions list <policy-id>

GETs /v1/projects/{project_id}/policies/{policy_id}/revisions. Pages a Policy's append-only revision history via --cursor / --limit. The text render lists each revision's id, Policy id, parent id (- on the initial revision), rule count, and creation timestamp.

plexctl policy revisions get <policy-id> <revision-id>

GETs /v1/projects/{project_id}/policies/{policy_id}/revisions/{revision_id}. Local UUID validation rejects a malformed policy-id or revision-id with exit 2.

plexctl policy diff <policy-id>

GETs /v1/projects/{project_id}/policies/{policy_id}/diff with the from_revision and to_revision query parameters bound from the required --from / --to flags. The text render emits one row per changed rule, tagged added, removed, or modified, with the source CIDR, destination CIDR, protocol, and action.

plexctl policy dry-run <policy-id>

POSTs /v1/projects/{project_id}/policies/{policy_id}/dry-run to evaluate a candidate revision against the current Project state without writing anything. The candidate is read from the --revision-yaml document (a file path, or - to read stdin), parsed the same way as update. The text render summarises the matched node count, affected peer pairs, the added / removed / modified rule counts, and the unreachable node count.

Flags

plexctl policy list

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--limit	int	no	Maximum items per page (server default when zero).
--cursor	string	no	Continuation token returned by a previous call's next_cursor.

plexctl policy get <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.

plexctl policy update <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--revision-yaml	path	yes	Path to a YAML revision document, or - to read stdin.

plexctl policy delete <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--reason	string	yes	Audit-recorded deletion rationale (echoed to stderr; no wire channel yet).
--yes (persistent)	bool	yes	Required confirmation for the destructive operation.

plexctl policy revisions list <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--limit	int	no	Maximum items per page (server default when zero).
--cursor	string	no	Continuation token returned by a previous call's next_cursor.

plexctl policy revisions get <policy-id> <revision-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.

plexctl policy diff <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--from	UUID	yes	Source revision UUID.
--to	UUID	yes	Target revision UUID.

plexctl policy dry-run <policy-id>

Flag	Type	Required	Description
--project-id	UUID	yes	Owning Project UUID.
--revision-yaml	path	yes	Path to a YAML revision document, or - to read stdin.

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 Policies of a Project

export PLEXSPHERE_URL="${PLEXSPHERE_URL:-https://localhost:8080}"

plexctl policy list \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0

Update a Policy from a YAML revision document

cat <<'YAML' | plexctl policy update 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0d0 \
  --server        "${PLEXSPHERE_URL}" \
  --project-id    0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --revision-yaml -
display_name: web tier
selector:
  source: env=prod
  destination: env=prod
rules:
  - action: allow
    protocol: tcp
    source_cidr: 10.0.0.0/8
    destination_cidr: 10.0.0.0/8
    ports:
      from: 443
      to: 443
YAML

Diff two revisions

plexctl policy diff 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0d0 \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --from       0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e1 \
  --to         0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e2

Dry-run a candidate revision

plexctl policy dry-run 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0d0 \
  --server        "${PLEXSPHERE_URL}" \
  --project-id    0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --revision-yaml /var/policies/candidate.yaml

Delete a Policy (requires --yes and --reason)

plexctl policy delete 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0d0 \
  --server     "${PLEXSPHERE_URL}" \
  --project-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --reason     decommissioned \
  --yes

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml
• ../../../cmd/plexctl/commands/policy.go
• ../../api/policy.md