How might we improve the consistency of Pepr's CLI?

[samayer12]

We noticed that Pepr has some inconsistent CLI behavior while working on #2086. As a starting point, we hypothesize that the following contributes to a positive CLI experience:

1. Use consistent, descriptive long-flag names (e.g., --namespace, not --ns).
2. Pair short and long flags predictably (-n for --namespace, -o for --output).
3. Provide --help with clear formatting and examples.
4. Apply consistent default behaviors (e.g., --output defaults to table).
5. Avoid conflicts and ambiguous flags; prefer clarity over cleverness.
6. Mark required flags and fail fast with helpful messages.
7. Use enum-style flags with well-defined choices (e.g., --output [table|json|yaml]).

A proposed set of CLI options that attempts to follow the above goals is shown in this section as a .csv listing. Let us know what you think! Are any of the CLI options poor choices? Does some of the suggested behavior conflict with common behavior that we see elsewhere in the Kubernetes ecosystem?

command, short-option, long-option, description
"build", "-P", "--with-pull-secret [name]", "Image Pull Secret: Use image pull secret for controller Deployment."
"build", "-R", "--rbac-mode <admin|scoped>", "RBAC mode for deployments. Options: admin, scoped. Default: admin"
"build", "-R", "--registry-info <registry/username>", "Provide the image registry and username for building a custom WASM container. Requires authentication."
"build", "-c", "--custom-name [name]", "Specify a custom name for zarf component and service monitors in helm charts."
"build", "-e", "--entry-point <file>", "Specify the entry point file to build with."
"build", "-h", "--help"
"build", "-i", "--custom-image <image>", "Specify a custom image (including version) for deployments. Example: 'docker.io/username/custom-pepr-controller:v1.0.0'"
"build", "-n", "--no-embed", "Disable embedding of deployment files into output module. Useful when creating library modules intended solely for reuse/distribution via NPM."
"build", "-o", "--output-dir <directory>", "Define where to place build output."
"build", "-r", "--registry [GitHub|Iron Bank]", "Container registry: Choose container registry for deployment manifests. Cannot be used with --custom-image."
"build", "-t", "--timeout [seconds]", "How long the API server should wait for a webhook to respond before treating the call as a failure."
"build", "-z", "--zarf [manifest|chart]", "Zarf package type. Options: manifest, chart. Default: manifest"
"crd create", "-S", "--scope [Namespaced|Cluster]", "Whether the resulting custom resource is cluster- or namespace-scoped. Default: Namespaced"
"crd create", "-d", "--domain [domain]", "Optional domain for CRD. Example: pepr.dev"
"crd create", "-g", "--group <group>", "API Group (e.g. cache)"
"crd create", "-h", "--help", "Display help for command"
"crd create", "-k", "--kind", "Kind name (e.g., memcached)"
"crd create", "-p", "--plural <plural>", "Plural name for CRD. Example: memcacheds"
"crd create", "-s", "--short-name [name]", "Short name for CRD. Example: mc"
"crd create", "-v", "--version", "API Version (e.g., v1alpha1)"
"crd generate", "-h", "--help", "Display help for command"
"crd generate", "-o", "--output [directory]", "Output directory for generated CRDs. Default: ./crds"
"deploy", "-E", "--docker-email <email>", "Email for Docker registry."
"deploy", "-P", "--docker-password <password>", "Password for Docker registry."
"deploy", "-S", "--docker-server <server>", "Docker server address."
"deploy", "-U", "--docker-username <username>", "Docker registry username."
"deploy", "-f", "--force", "Force deploy the module, override manager field."
"deploy", "-h", "--help", "Display help for command"
"deploy", "-i", "--image [image]", "Override the image tag."
"deploy", "-p", "--pull-secret <name>", "Deploy imagePullSecret for Controller private registry."
"deploy", "-y", "--yes", "Skip confirmation prompts."
"dev", "-H", "--host <hostname>", "Host to listen on. Default: host.k3d.internal"
"dev", "-h", "--help", "Display help for command"
"dev", "-y", "--yes", "Skip confirmation prompts."
"format", "-h", "--help", "Display help for command"
"format", "-v", "--validate-only", "Do not modify files, only validate formatting. - UNDOCUMENTED!"
"init", "-d", "--description <string>", "Explain the purpose of the new module."
"init", "-e", "--error-behavior <audit|ignore|reject>", "Set an errorBehavior."
"init", "-h", "--help", "Display help for command"
"init", "-k", "--skip-post-init", "Skip npm install, git init, and VSCode launch after initialization."
"init", "-m", "--name <string>", "Set the name of the new module."
"init", "-u", "--uuid [string]", "Unique identifier for your module with a max length of 36 characters."
"init", "-y", "--yes", "Skip verification prompt when creating a new module."
"kfc", "-h", "--help", "Display help for command"
"monitor", "-h", "--help", "Display help for command"
"pepr", "-V", "--version", "Display the version of the Pepr CLI."
"pepr", "-h", "--help", "Display help for command"
"update", "-K", "--skip-template-update", "Skip updating the template files."
"update", "-h", "--help", "Display help for command"
"uuid", "-h", "--help", "Display help for command"

[cmwylie19]

Lets create issues and get this done before v1 and prioritize this sprint.

[tamirazrab]

Is it intentional that both --rbac-mode and --registry-info use the -R short flag in the build command? Just want to confirm if this is expected behavior or an oversight.

[samayer12]

Good catch. That's an oversight, they should not both use the -R short flag. We'd welcome an alternative CLI option if you have any suggestions. Otherwise, we should probably just use the long flags for each option and not support a short-flag to avoid ambiguity.

For convenience, these are the two conflicting options listed above.

"build", "-R", "--rbac-mode <admin|scoped>", "RBAC mode for deployments. Options: admin, scoped. Default: admin"
"build", "-R", "--registry-info <registry/username>", "Provide the image registry and username for building a custom WASM container. Requires authentication."

[tamirazrab]

I'd say:

• -B for --rbac-mode (b from "rbac")
• -I for --registry-info (i from "info")

Most users will still prefer short flags to save keystrokes, in favor to offer short non-conflicting flags than drop them entirely.

[samayer12]

In pepr #2383 the proposed pepr build options are now:

  -M, --rbac-mode <admin|scoped>           Set RBAC mode. (choices: "admin", "scoped", default: "admin")
  -I, --registry-info <registry/username>  Provide the image registry and username for building and pushing a custom WASM container. Requires
                                           authentication. Conflicts with --custom-image and --registry. Builds and pushes
                                           `'<registry/username>/custom-pepr-controller:<current-version>'`.
  -P, --with-pull-secret <name>            Use image pull secret for controller Deployment. (default: "")
  -c, --custom-name <name>                 Set name for zarf component and service monitors in helm charts.
  -e, --entry-point <file>                 Specify the entry point file to build with. (default: "pepr.ts")
  -i, --custom-image <image>               Specify a custom image with version for deployments. Conflicts with --registry-info and --registry. Example:
                                           'docker.io/username/custom-pepr-controller:v1.0.0'
  -n, --no-embed                           Disable embedding of deployment files into output module. Useful when creating library modules intended solely
                                           for reuse/distribution via NPM.
  -o, --output <directory>                 Set output directory.
  -r, --registry <GitHub|Iron Bank>        Container registry: Choose container registry for deployment manifests. Conflicts with --custom-image and
                                           --registry-info. (choices: "GitHub", "Iron Bank")
  -t, --timeout <seconds>                  How long the API server should wait for a webhook to respond before treating the call as a failure.
  -z, --zarf <manifest|chart>              Set Zarf package type (choices: "manifest", "chart", default: "manifest")
  -h, --help                               display help for command