plexctl completion

plexctl completion <shell> writes a shell-completion script for plexctl to stdout. Pipe the output into the shell-specific autoload location for your platform.

One contract is pinned: the first line of every generated script is a stable, language-appropriate marker so a future cobra upgrade that drops a shell or rewrites the preamble fails CI rather than silently degrading the operator experience. The four markers are:

Shell	First-line marker
bash	# bash completion for plexctl
zsh	#compdef plexctl
fish	# fish completion for plexctl
powershell	# powershell completion for plexctl

DECISION: the bash branch uses cobra's GenBashCompletion (V1) rather than GenBashCompletionV2. The V1 script begins with the contract-pinned marker # bash completion for plexctl; the V2 script begins with # bash completion V2 for plexctl, which would silently drift the public marker. Distributors who need V2 can move to it explicitly when the marker contract is amended.

The shell argument is matched exactly — no trimming of trailing whitespace, no case-folding. Bash (capital B) is rejected as an unknown shell rather than silently emitting the wrong format.

Synopsis

plexctl completion <bash|zsh|fish|powershell>

Invocation

The command takes exactly one positional argument: the shell name. No flags are defined on the subcommand itself.

Flags

Flag	Type	Required	Default	Description
(positional) <shell>	enum	yes	—	One of bash, zsh, fish, powershell.

Persistent flags inherited from root: see plexctl.md. The completion subcommand does not require credentials; it does not contact the server.

Exit codes

Code	Reachable	Meaning
0	success	The completion script was written to stdout.
1	runtime error	The underlying writer returned an error while emitting the script.
2	flag-parse / input validation	Wrong number of positional arguments (cobra ExactArgs(1)), or an unsupported shell name (unknown shell "Bash"). The shell-name check returns a typed input-validation error, which the dispatcher routes to exit 2.
3	none	The command does not require credentials.
4	none	The command does not contact the server.
64	none	Not a deferred command.

Examples

Bash — system-wide install

plexctl completion bash | sudo tee /etc/bash_completion.d/plexctl >/dev/null
# Verify the marker line:
head -n 1 /etc/bash_completion.d/plexctl
# # bash completion for plexctl

Open a new shell (or source /etc/bash_completion.d/plexctl) to load the completions.

Zsh — per-user fpath install

plexctl completion zsh > "${fpath[1]}/_plexctl"
# Verify the marker line:
head -n 1 "${fpath[1]}/_plexctl"
# #compdef plexctl

Run compinit (or open a new shell) to pick up the new completion.

Fish — per-user install

plexctl completion fish > ~/.config/fish/completions/plexctl.fish
# Verify the marker line:
head -n 1 ~/.config/fish/completions/plexctl.fish
# # fish completion for plexctl

Fish auto-loads completions from ~/.config/fish/completions/ on the next shell start.

PowerShell — dot-source from your profile

plexctl completion powershell > $HOME\plexctl.ps1
# Verify the marker line:
Get-Content -TotalCount 1 $HOME\plexctl.ps1
# # powershell completion for plexctl

Add . $HOME\plexctl.ps1 to your $PROFILE to load completions on shell start.

Refusal: unknown shell (exit 2)

plexctl completion Bash
# stderr: plexctl: unknown shell "Bash"; expected bash|zsh|fish|powershell
echo "exit=$?"   # exit=2

Refusal: missing positional argument (exit 2)

plexctl completion
# stderr: Error: accepts 1 arg(s), received 0
echo "exit=$?"   # exit=2

Cross-references

• ../../../cmd/plexctl/commands/completion.go — source of truth for the cobra subcommand wiring, the V1-vs-V2 bash decision, and the four contract-pinned marker lines.
• ../../../api/openapi/plexsphere-v1.yaml — OpenAPI 3.1 source of truth for the /v1 surface that the completed commands ultimately call (the completion subcommand itself does not contact the server).
• plexctl.md — root command reference (persistent flags, profile resolution, shared exit-code taxonomy).