porchctl CLI Architecture#

porchctl is the CLI for Porch (Package Orchestration). Its commands live under pkg/cli/commands/rpkg/, organized as one directory per subcommand plus a shared docs/ package and utility package 1.

Directory Layout#

pkg/cli/commands/rpkg/
├── approve/ # porchctl rpkg approve
├── clone/ # porchctl rpkg clone
├── copy/ # porchctl rpkg copy
├── del/ # porchctl rpkg del
├── docs/ # shared documentation strings (docs.go)
├── get/ # porchctl rpkg get
├── init/ # porchctl rpkg init
├── propose/ # porchctl rpkg propose
├── proposedelete/ # porchctl rpkg propose-delete
├── pull/ # porchctl rpkg pull
├── push/ # porchctl rpkg push
├── reject/ # porchctl rpkg reject
├── upgrade/ # porchctl rpkg upgrade
├── util/ # shared CLI utilities
├── rpkgcmd.go # top-level rpkg command; wires all subcommands
└── rpkgcmd_test.go

The top-level rpkg command is assembled in rpkgcmd.go, which calls each subcommand's NewCommand() and adds it via cobra.Command.AddCommand() 2.

docs.go vs. command.go Separation#

Every subcommand splits its concerns across two files:

docs/docs.go is a single shared file (349 lines, originally generated by mdtogo but now manually maintained) that exports named string constants — e.g. GetShort, GetLong, GetExamples, CloneShort, CloneLong, etc. 3. Each string contains the full prose description of the command, its arguments, flags with extended constraint text, and example invocations.

command.go imports the docs package and wires the strings into the Cobra command at construction time 4:

cmd := &cobra.Command{
    Short: docs.GetShort,
    Long: docs.GetShort + "\n" + docs.GetLong,
    Example: docs.GetExamples,
    ...
}

Flag registration happens immediately after, also in command.go 5:

cmd.Flags().StringVar(&r.packageName, "name", "", "...")
cmd.Flags().BoolVar(&r.showKptfile, "show-kptfile", false, "...")

Note the two-layer flag description:

• The inline string in cmd.Flags().BoolVar(...) provides a one-line hint shown in --help.
• The full constraint text (e.g., "Cannot be combined with --name, --revision, --workspace, or --all-namespaces") lives only in docs.go 3.

A concrete example is --show-kptfile on rpkg get, added in PR #513: the long description and constraint rules were added to docs/docs.go, while validation logic (preRunShowKptfile) and flag binding were added to get/command.go 6.

Similarly, --subpackage-dir on rpkg clone and rpkg upgrade documents flag constraints in docs.go 3 while the flag registration and execution path split live in their respective command.go files 7.

Branch Management Implications#

Because docs.go and each command.go are separate files, cherry-picking between branches requires picking both files together. Omitting either half produces mismatches:

• Docs without implementation: A flag appears in --help output but calling it returns an error or is silently ignored.
• Implementation without docs: A flag is functional but invisible in the help text, making it undiscoverable.

This played out concretely during PR #1027, which cherry-picked subpackage clone/upgrade support to the 1.5 branch 8. The cherry-pick had to pull in changes from five upstream PRs:

• PR #1022 — porchctl CLI implementation (clone/command.go, upgrade/command.go)
• PR #1038 — flag documentation in docs/docs.go

Because PR #1038 was initially documentation-only (the implementation arrived separately in PR #1022), cherry-picking only one of these to a release branch would have left the feature incomplete 8.

Rule of thumb when cherry-picking or reviewing: treat docs/docs.go and the relevant command.go as a single logical unit for any flag addition or change.

Key Source Files#

Reference PRs:

• PR #513 — --show-kptfile on rpkg get: canonical example of the docs/command split 6
• PR #1027 — cherry-pick to 1.5 branch: example of cross-file sync risk 8