plexctl label

Synopsis

plexctl label is the operator surface for the Label aggregate. It spans three independent /v1 surfaces under a single cobra parent:

• /v1/label-definitions — CRUD on Label Definitions (the schema for a label key plus its value contract).
• /v1/labels/selectors/preview — parser tester that walks a raw selector expression and renders either the parsed AST or the list of parse errors the server returned.
• /v1/objects/{kind}/{id}/labels — per-object Assignment management: set (upsert), list, delete.

The Label context's ubiquitous language (Definition vs. Assignment, qualified key, value-schema kind, on-delete policy) is documented in ../../contexts/labels/index.md. This page documents only the CLI surface: every flag, every required input, and the exit-code mapping.

Invocation

plexctl label define <subcommand> [flags]
plexctl label selector preview --selector <expression>
plexctl label object <subcommand> <kind:id> [flags]

The <kind:id> positional argument addresses an object by its kind discriminator and UUID — for example node:0190a8b8-… or project:0190a8b8-…. Malformed references fail before the wire so an operator typo does not blow past flag-parse and surface as a 404 .

plexctl label define create

Creates a Label Definition. The --type flag is checked against the OpenAPI ValueSchemaKind enum at flag-parse time, so an invalid kind surfaces as exit 2 instead of a 400 round-trip.

plexctl label define list

Lists Label Definitions in a scope. The --scope flag carries the OpenAPI's compact scope coordinate: platform, domain:<uuid>, or project:<uuid>. Pagination is keyset-based via --cursor.

plexctl label define get

Returns a single Label Definition by UUID.

plexctl label define update

Updates a Label Definition's mutable fields. scope, scope_id, local_key, and immutable are frozen after creation per the OpenAPI contract.

plexctl label define delete

Deletes a Label Definition. Requires the persistent --yes flag — delete is destructive and the policy on Definition delete (block / cascade / orphan) is encoded on the Definition itself, not on this command.

plexctl label selector preview

POSTs a raw selector expression to /v1/labels/selectors/preview and renders the parsed AST in text mode (depth-first walk, one row per node) or the typed wire shape in json / yaml mode. When the server returns parse errors, each error renders as an ERROR row with the offending position.

plexctl label object set

Upserts a Label Assignment on an object. The --value flag is sent as a string literal; the server validates against the parent Definition's value-schema (boolean / numeric / regex / enum / string).

plexctl label object list

Lists every Label Assignment on an object.

plexctl label object delete

Deletes a Label Assignment from an object. The Assignment is addressed by qualified key (e.g. platform/env) — addressing by Definition id would force a lookup hop, so the CLI mirrors the wire shape. Like label define delete, this subcommand requires the persistent --yes flag: removing an Assignment is destructive, so the API call is refused until the operator confirms intent.

Flags

plexctl label define create

Flag	Type	Required	Default	Description
--scope	enum	yes	—	platform | domain | project.
--scope-id	UUID	conditional	—	Scope UUID. Required when --scope=domain or --scope=project.
--key	string	yes	—	Local key, e.g. env.
--type	enum	yes	—	Value-schema kind: string | enum | boolean | numeric | regex.
--applicable-kinds	string slice	yes	—	Object kinds the Definition applies to (repeat or comma-separate).
--description	string	no	—	Human description (max 512 chars).
--required	bool	no	false	Assignments mandatory on every applicable object.
--immutable	bool	no	false	Freeze the value schema and Assignment values after creation.
--cardinality	int	no	0	Per-object Assignment cap (0 = unlimited).
--on-delete	enum	no	server default	Policy on Definition delete: block | cascade | orphan.
--enum-values	string slice	conditional	—	Permitted values for --type=enum.
--regex-pattern	string	conditional	—	Go regexp pattern for --type=regex.
--max-len	int	no	—	Maximum byte length for --type=string.
--min	int64	no	—	Lower bound for --type=numeric.
--max	int64	no	—	Upper bound for --type=numeric.

plexctl label define list

Flag	Type	Required	Default	Description
--scope	string	yes	—	Scope coordinate: platform | domain:<uuid> | project:<uuid>.
--limit	int	no	server default	Maximum items per page.
--cursor	string	no	—	Continuation token from a previous call's next_cursor.

plexctl label define get

Flag	Type	Required	Default	Description
--id	UUID	yes	—	Label Definition UUID.

plexctl label define update

Flag	Type	Required	Default	Description
--id	UUID	yes	—	Label Definition UUID.
--description	string	no	—	New human description (max 512 chars).
--applicable-kinds	string slice	no	—	New list of applicable object kinds.
--required	bool	no	—	New required flag.
--on-delete	enum	no	—	Policy on Definition delete: block | cascade | orphan.

Only flags explicitly set on the command line are sent in the PATCH body — unset flags leave the server-side value untouched.

plexctl label define delete

Flag	Type	Required	Default	Description
--id	UUID	yes	—	Label Definition UUID.
--yes (persistent)	bool	yes	false	Required confirmation for the destructive operation.

plexctl label selector preview

Flag	Type	Required	Default	Description
--selector	string	yes	—	Raw selector expression to parse-test.

plexctl label object set

Positional	Type	Required	Description
<kind:id>	string	yes	Object reference, e.g. node:0190a8b8-….

Flag	Type	Required	Default	Description
--definition-id	UUID	yes	—	Parent Label Definition UUID.
--value	string	yes	—	Assignment value as a literal. The server validates it against the parent Definition's value schema.

plexctl label object list

Positional	Type	Required	Description
<kind:id>	string	yes	Object reference, e.g. node:0190a8b8-….

plexctl label object delete

Positional	Type	Required	Description
<kind:id>	string	yes	Object reference, e.g. node:0190a8b8-….

Flag	Type	Required	Default	Description
--qualified-key	string	yes	—	Fully-qualified Label key, e.g. platform/env.
--yes (persistent)	bool	yes	false	Required confirmation for the destructive operation.

Persistent flags inherited from root

--server, --profile, --token-file, --output, --yes, --reveal-secrets. The --yes flag is consumed by define delete and object delete (the destructive label subcommands); the others apply unchanged. See plexctl.md for the canonical list.

Exit codes

plexctl collapses every failure into the taxonomy below; the single source of truth is exitCodeFor in ../../../cmd/plexctl/app.go.

Code	Reachable	Meaning
0	yes	The API returned the expected status (201 for define create, 200 for list / get / update / preview / object set / object list, 204 for the deletes).
1	yes	Runtime / API error: transport failure, unexpected status code, a malformed response body, or a delete subcommand invoked without the persistent --yes flag.
2	yes	Flag-parse / misconfiguration: missing required flag, malformed UUID, or an unknown --type / --scope / --on-delete value.
3	yes	Missing or insecure credentials, or 401 Unauthorized from the API.
4	yes	Permission denied: 403 Forbidden from the API (e.g. the operator lacks domain:manage on a domain-scoped Definition).
64	no	Not reachable — label is fully implemented and never returns *NotImplementedError.

Examples

Create an enum Label Definition

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

plexctl label define create \
  --server           "${PLEXSPHERE_URL}" \
  --scope            domain \
  --scope-id         0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a0 \
  --key              env \
  --type             enum \
  --applicable-kinds node,project \
  --enum-values      prod,staging,dev \
  --required         \
  --on-delete        block

Parse-test a selector

plexctl label selector preview \
  --server   "${PLEXSPHERE_URL}" \
  --selector 'env in (prod, staging) AND tier = backend' \
  --output   json

Set a Label on a Node

plexctl label object set node:0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0e0 \
  --server        "${PLEXSPHERE_URL}" \
  --definition-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1 \
  --value         prod

Permission denied on a domain-scoped Definition (exit 4)

plexctl label define delete \
  --server "${PLEXSPHERE_URL}" \
  --id     0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0a1 \
  --yes
# stderr: plexctl: 403 Forbidden: insufficient_relation (need domain:manage)
echo $?  # 4

Cross-references

• ../../../api/openapi/plexsphere-v1.yaml — CreateLabelDefinition, ListLabelDefinitions, GetLabelDefinition, UpdateLabelDefinition, DeleteLabelDefinition, PreviewLabelSelector, PutObjectLabel, ListObjectLabels, DeleteObjectLabel operation definitions and the LabelDefinition, LabelDefinitionListResponse, LabelAssignment, LabelAssignmentList, LabelSelectorPreviewResponse schemas.
• ../../contexts/labels/index.md — bounded-context reference for the Label aggregate, the value schema kinds, the qualified-key contract, the on-delete policy matrix, and the selector grammar.
• ../../../cmd/plexctl/commands/label.go — source of truth for the cobra command, flag wiring, the AST walk in text mode, and the kind:id parser.