plexctl action

Synopsis

plexctl action is the operator surface for the Action Orchestrator. It dispatches a remote action against a single Node or a selector-resolved cohort and reads back the resulting Executions. The family is a thin wrapper over the typed /v1/projects/{project_id}/executions* operations — every invariant is server-authoritative.

A dispatch targets exactly one of a single --node or an opaque label --selector; supplying both, or neither, is rejected before the request leaves the CLI.

plexctl action dispatch --project <uuid> --action <name> (--node <uuid> | --selector <expr>) [flags]
plexctl action list     --project <uuid> [flags]
plexctl action get      --project <uuid> --id <uuid>

Subcommands

plexctl action dispatch

POSTs /v1/projects/{project_id}/executions:dispatch and renders the minted Execution. The dispatch accepts either 202 Accepted (asynchronous fan-out) or 200 OK (synchronous cohort resolution). The --node and --selector flags are mutually exclusive and exactly one is required; both-set and neither-set are local input-validation errors that exit 2. The optional --type selects the action kind (builtin or hook; the server defaults to builtin) and --timeout-seconds sets a per-dispatch execution timeout.

plexctl action list

GETs /v1/projects/{project_id}/executions and renders one row per visible Execution. Pagination is cursor-based via --cursor / --limit; the response carries a next_cursor the caller threads into the next --cursor to walk the pages. The optional --status and --action-name filters narrow the page and are passed through to the server as query parameters.

plexctl action get

GETs /v1/projects/{project_id}/executions/{execution_id} and renders a single Execution by id. Both --project and --id are required and parsed as UUIDs locally; a malformed value exits 2.

Flags

plexctl action dispatch

Flag	Type	Required	Description
--project	string (UUID)	yes	Owning Project UUID.
--action	string	yes	Name of the action to dispatch.
--node	string (UUID)	one of	Single target Node UUID. Mutually exclusive with --selector.
--selector	string	one of	Opaque label selector resolving the target cohort. Mutually exclusive with --node.
--type	string	no	Kind of action: builtin or hook (server defaults to builtin).
--timeout-seconds	int	no	Per-dispatch execution timeout in whole seconds.

plexctl action list

Flag	Type	Required	Description
--project	string (UUID)	yes	Owning Project UUID.
--status	string	no	Aggregate-status filter (pending, ack, started, succeeded, failed, cancelled, timeout).
--action-name	string	no	Filter by action name.
--cursor	string	no	Continuation token returned by a previous call's next_cursor.
--limit	int	no	Maximum items per page (server default when zero).

plexctl action get

Flag	Type	Required	Description
--project	string (UUID)	yes	Owning Project UUID.
--id	string (UUID)	yes	Execution UUID to fetch.

Persistent flags inherited from root

--server, --profile, --token-file, --output. See ../plexctl.md for the canonical list.

Exit codes

See ../plexctl.md#exit-code-taxonomy for the inherited base table. The cases that apply to this family, including the dispatch-specific Problem-code mappings:

Code	Trigger
0	The Execution(s) were rendered to stdout.
1	Transport or API failure, a 5xx, a 429 capacity_exceeded (per-Domain dispatch budget ceiling), or a 409 hook_integrity_violation (server-side hook catalog conflict).
2	Malformed UUID, a missing required flag, both/neither --node/--selector, or a 422 selector_empty_cohort (the selector matched no Nodes — widen it and re-issue).
3	Missing or insecure credentials, a 401 Unauthorized, or a 401 step_up_required (re-authenticate before retrying).
4	403 Forbidden.
77	ReBAC denial (403 Forbidden with code == "rebac_denied").

Examples

Dispatch a built-in action to a single Node

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

plexctl action dispatch \
  --server  "${PLEXSPHERE_URL}" \
  --project 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --action  restart-agent \
  --node    0190a8b8-b1c1-7b1b-8b1b-b1b1b1b1b1b1

Dispatch a hook to a label-resolved cohort with a timeout

plexctl action dispatch \
  --server          "${PLEXSPHERE_URL}" \
  --project         0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --action          rotate-keys \
  --type            hook \
  --selector        'env=prod,tier=edge' \
  --timeout-seconds 120

List the failed executions of a Project

plexctl action list \
  --server  "${PLEXSPHERE_URL}" \
  --project 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --status  failed

Get a single execution

plexctl action get \
  --server  "${PLEXSPHERE_URL}" \
  --project 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --id      0190a8b8-c2d2-7c2c-8c2c-c2c2c2c2c2c2 \
  --output  json

Cross-references

• ../../../../api/openapi/plexsphere-v1.yaml
• ../../../../cmd/plexctl/commands/action.go
• ../../../contexts/actions/model.md