Skip to content

commands should provide help when called w/o arguments if they require inputs #264

@jsoref

Description

@jsoref

cmctl

% cmctl

cmctl is a CLI tool manage and configure cert-manager resources for Kubernetes

Usage:
  cmctl [command]

Available Commands:
  approve      Approve a CertificateRequest
  check        Check cert-manager components
  completion   Generate completion scripts for the cert-manager CLI
  convert      Convert cert-manager config files between different API versions
  create       Create cert-manager resources
  deny         Deny a CertificateRequest
  experimental Interact with experimental features
  help         Help about any command
  inspect      Get details on certificate related resources
  renew        Mark a Certificate for manual renewal
  status       Get details on current status of cert-manager resources
  upgrade      Tools that assist in upgrading cert-manager
  version      Print the cert-manager CLI version and the deployed cert-manager version

Flags:
  -h, --help                           help for cmctl
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl [command] --help" for more information about a command.

cmctl approve

% cmctl approve
error: the name of the CertificateRequest to approve has to be provided as an argument

cmctl check

% cmctl check
Check cert-manager components

Usage:
  cmctl check [command]

Available Commands:
  api         Check if the cert-manager API is ready

Flags:
  -h, --help   help for check

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl check [command] --help" for more information about a command.

cmctl check api

% cmctl check api
The cert-manager API is ready

✔️

cmctl completion

% cmctl completion
Generate completion for the cert-manager CLI so arguments and flags can be suggested and auto-completed

Usage:
  cmctl completion [command]

Available Commands:
  bash        Generate cert-manager CLI scripts for a Bash shell
  fish        Generate cert-manager CLI scripts for a Fish shell
  powershell  Generate cert-manager CLI scripts for a PowerShell shell
  zsh         Generation cert-manager CLI scripts for a ZSH shell

Flags:
  -h, --help   help for completion

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl completion [command] --help" for more information about a command.

cmctl completion bash

% cmctl completion bash|tail -1
# ex: ts=4 sw=4 et filetype=sh

✔️

cmctl completion fish

% cmctl completion fish|tail -1
complete -k -c cmctl -n '__cmctl_requires_order_preservation && __cmctl_prepare_completions' -f -a '$__cmctl_comp_results'

✔️

cmctl completion zsh

% cmctl completion zsh|tail -1
fi

✔️

cmctl completion powershell

% cmctl completion powershell|tail -1
Register-ArgumentCompleter -CommandName 'cmctl' -ScriptBlock ${__cmctlCompleterBlock}

✔️

% cmctl completion whatever

See cmctl completion

cmctl convert

% cmctl convert
error: must specify one of -f and -k

cmctl create

% cmctl create
Create cert-manager resources e.g. a CertificateRequest

Usage:
  cmctl create [command]

Available Commands:
  certificaterequest Create a cert-manager CertificateRequest resource, using a Certificate resource as a template

Flags:
  -h, --help   help for create

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl create [command] --help" for more information about a command.

cmctl create certificaterequest

% cmctl create certificaterequest
error: the name of the CertificateRequest to be created has to be provided as argument

cmctl deny

% cmctl deny
error: the name of the CertificateRequest to deny has to be provided as an argument

cmctl experimental

% cmctl experimental
Interact with experimental features

Usage:
  cmctl experimental [command]

Aliases:
  experimental, x

Available Commands:
  create      Create cert-manager resources
  install     Install cert-manager
  uninstall   Uninstall cert-manager

Flags:
  -h, --help   help for experimental

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl experimental [command] --help" for more information about a command.

cmctl experimental create

% cmctl experimental create
Create cert-manager resources e.g. a CertificateRequest

Usage:
  cmctl experimental create [command]

Available Commands:
  certificatesigningrequest Create a Kubernetes CertificateSigningRequest resource, using a Certificate resource as a template

Flags:
  -h, --help   help for create

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl experimental create [command] --help" for more information about a command.

cmctl experimental create certificatesigningrequest

error: the name of the CertificateSigningRequest to be created has to be provided as argument

cmctl experimental install

% cmctl experimental install --help
This command installs cert-manager. It uses the Helm libraries to do so.

The latest published cert-manager chart in the "https://charts.jetstack.io" repo is used.
Most of the features supported by 'helm install' are also supported by this command.
In addition, this command will always correctly install the required CRD resources.

Some example uses:
	$ cmctl x install
or
	$ cmctl x install -n new-cert-manager
or
	$ cmctl x install --version v1.4.0
or
	$ cmctl x install --set prometheus.enabled=false

To override values in the cert-manager chart, use either the '--values' flag and
pass in a file or use the '--set' flag and pass configuration from the command line.

Usage:
  cmctl experimental install [flags]

Flags:
      --as string                      Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --as-uid string                  UID to impersonate for the operation.
      --cache-dir string               Default cache directory (default "/Users/jsoref/.kube/cache")
      --certificate-authority string   Path to a cert file for the certificate authority
      --client-certificate string      Path to a client certificate file for TLS
      --client-key string              Path to a client key file for TLS
      --cluster string                 The name of the kubeconfig cluster to use
      --context string                 The name of the kubeconfig context to use
      --disable-compression            If true, opt-out of response compression for all requests to the server
      --dry-run                        Simulate install and output manifest
  -h, --help                           help for install
      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
  -n, --namespace string               If present, the namespace scope for this CLI request (default "cert-manager")
      --registry-config string         path to the registry config file (default "/Users/jsoref/Library/Preferences/helm/registry/config.json")
      --repository-cache string        path to the directory containing cached repository indexes (default "/Users/jsoref/Library/Caches/helm/repository")
      --repository-config string       path to the file containing repository names and URLs (default "/Users/jsoref/Library/Preferences/helm/repositories.yaml")
      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
  -s, --server string                  The address and port of the Kubernetes API server
      --set stringArray                Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
      --tls-server-name string         Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
      --token string                   Bearer token for authentication to the API server
      --user string                    The name of the kubeconfig user to use
  -f, --values strings                 Specify values in a YAML file or a URL (can specify multiple)
      --version string                 specify a version constraint for the chart version to use. This constraint can be a specific tag (e.g. 1.1.1) or it may reference a valid range (e.g. ^2.0.0). If this is not specified, the latest version is used

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

cmctl experimental uninstall

% cmctl experimental uninstall
I0811 12:41:22.743612   65485 settings.go:120] "uninstall: Deleting cert-manager" logger="cert-manager.cmctl"
I0811 12:41:22.976962   65485 settings.go:120] "uninstall: Failed to delete release: [unable to build kubernetes objects for delete: [resource mapping not found for name: \"cert-manager-cainjector:leaderelection\" namespace: \"kube-system\" from \"\": no matches for kind \"RoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager:leaderelection\" namespace: \"kube-system\" from \"\": no matches for kind \"RoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-cainjector:leaderelection\" namespace: \"kube-system\" from \"\": no matches for kind \"Role\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager:leaderelection\" namespace: \"kube-system\" from \"\": no matches for kind \"Role\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-cainjector\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-orders\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-challenges\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-clusterissuers\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-certificates\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-ingress-shim\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-issuers\" namespace: \"\" from \"\": no matches for kind \"ClusterRoleBinding\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-certificates\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-clusterissuers\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-cainjector\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-orders\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-ingress-shim\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-challenges\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-controller-issuers\" namespace: \"\" from \"\": no matches for kind \"ClusterRole\" in version \"rbac.authorization.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-webhook\" namespace: \"\" from \"\": no matches for kind \"MutatingWebhookConfiguration\" in version \"admissionregistration.k8s.io/v1beta1\"\nensure CRDs are installed first, resource mapping not found for name: \"cert-manager-webhook\" namespace: \"\" from \"\": no matches for kind \"ValidatingWebhookConfiguration\" in version \"admissionregistration.k8s.io/v1beta1\"\nensure CRDs are installed first]]" logger="cert-manager.cmctl"
release "cert-manager" uninstalled

☢️ 😵

  • Apparently this command is "safe" because it doesn't uninstall all of cert-manager, just the operating pieces (it leaves CRDs).
  • I'm not really sure I like the output here -- if it didn't do anything, then saying that it uninstalled a release seems disingenuous.
  • Even though this command is "safe", I'd much rather a model where the command w/o a --make-it-so/--just-do-it flag just showed the help (i.e. the current output from cmctl experimental uninstall --help) instead of running a somewhat significant operation....

cmctl experimental something

See cmctl experimental

cmctl help

% cmctl help

cmctl is a CLI tool manage and configure cert-manager resources for Kubernetes

Usage:
  cmctl [command]

Available Commands:
  approve      Approve a CertificateRequest
  check        Check cert-manager components
  completion   Generate completion scripts for the cert-manager CLI
  convert      Convert cert-manager config files between different API versions
  create       Create cert-manager resources
  deny         Deny a CertificateRequest
  experimental Interact with experimental features
  help         Help about any command
  inspect      Get details on certificate related resources
  renew        Mark a Certificate for manual renewal
  status       Get details on current status of cert-manager resources
  upgrade      Tools that assist in upgrading cert-manager
  version      Print the cert-manager CLI version and the deployed cert-manager version

Flags:
  -h, --help                           help for cmctl
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl [command] --help" for more information about a command.

👎

This isn't actually great.

It should really say:

cmctl help [command ...]

As, how else would I learn that I can run cmctl help x?

cmctl inspect

% cmctl inspect
Get details on certificate related resources, e.g. secrets

Usage:
  cmctl inspect [command]

Available Commands:
  secret      Get details about a kubernetes.io/tls typed secret

Flags:
  -h, --help   help for inspect

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl inspect [command] --help" for more information about a command.

cmctl inspect secret

% cmctl inspect secret
error: the name of the Secret has to be provided as argument

cmctl renew

% cmctl renew
error: please either supply one or more Certificate resource names, label selectors, or use the --all flag to renew all Certificate resources

cmctl status

% cmctl status
Get details on current status of cert-manager resources, e.g. Certificate

Usage:
  cmctl status [command]

Available Commands:
  certificate Get details about the current status of a cert-manager Certificate resource

Flags:
  -h, --help   help for status

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl status [command] --help" for more information about a command.

cmctl status certificate

% cmctl status certificate
error: the name of the Certificate has to be provided as argument

cmctl upgrade

% cmctl upgrade
Note: this command does NOT actually upgrade cert-manager installations

Usage:
  cmctl upgrade [command]

Available Commands:
  migrate-api-version Migrate all existing persisted cert-manager resources to the v1 API version

Flags:
  -h, --help   help for upgrade

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

Use "cmctl upgrade [command] --help" for more information about a command.

cmctl upgrade migrate-api-version

% cmctl upgrade migrate-api-version
Checking all CustomResourceDefinitions have storage version set to "v1"
All CustomResourceDefinitions have "v1" configured as the storage version.
Looking for CRDs that contain resources that require migrating to "v1"...
Nothing to do. cert-manager CRDs do not have "status.storedVersions" containing old API versions. You may proceed to upgrade to cert-manager v1.7.

🤷‍♂️

I guess it's harmless enough?

cmctl version

% cmctl version
Client Version: util.Version{GitVersion:"v2.3.0", GitCommit:"29b59b934c5a6f533b2d278f4541dca89d1eb288", GitTreeState:"", GoVersion:"go1.24.5", Compiler:"gc", Platform:"darwin/arm64"}
Server Version: &versionchecker.Version{Detected:"v1.13.3", Sources:map[string]string{"crdLabelVersion":"v1.13.3"}}

This is actually a bit confusing.

Consider:

kubectl version

% kubectl version
Client Version: v1.32.2
Kustomize Version: v5.5.0
Server Version: v1.32.6-gke.1025000

Note how the client version and server version share what appears to be a related version scheme? Whereas, It doesn't feel like v2.3.0 and v1.13.3 do?

cmctl version --help

% cmctl version --help
Print the cert-manager CLI version and the deployed cert-manager version.
The CLI version is embedded in the binary and directly displayed. Determining
the deployed cert-manager version is done by querying the cert-manger
resources.  First, the tool looks at the labels of the cert-manager CRD
resources. Then, it searches for the labels of the resources related the
cert-manager webhook linked in the CRDs.  It also tries to derive the version
from the docker image tag of that webhook service.  After gathering all this
version information, the tool checks if all versions are the same and returns
that version. If no version information is found or the found versions differ,
an error will be displayed.

The '--client' flag can be used to disable the logic that tries to determine the installed
cert-manager version.

Some example uses:
	$ cmctl version
or
	$ cmctl version --client
or
	$ cmctl version --short
or
	$ cmctl version -o yaml

Usage:
  cmctl version [flags]

Flags:
      --as string                      Username to impersonate for the operation. User could be a regular user or a service account in a namespace.
      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups.
      --as-uid string                  UID to impersonate for the operation.
      --cache-dir string               Default cache directory (default "/Users/jsoref/.kube/cache")
      --certificate-authority string   Path to a cert file for the certificate authority
      --client                         If true, shows client version only (no server required).
      --client-certificate string      Path to a client certificate file for TLS
      --client-key string              Path to a client key file for TLS
      --cluster string                 The name of the kubeconfig cluster to use
      --context string                 The name of the kubeconfig context to use
      --disable-compression            If true, opt-out of response compression for all requests to the server
  -h, --help                           help for version
      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
      --kubeconfig string              Path to the kubeconfig file to use for CLI requests.
  -n, --namespace string               If present, the namespace scope for this CLI request
  -o, --output string                  One of 'yaml' or 'json'.
      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (default "0")
  -s, --server string                  The address and port of the Kubernetes API server
      --short                          If true, print just the version number.
      --tls-server-name string         Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used
      --token string                   Bearer token for authentication to the API server
      --user string                    The name of the kubeconfig user to use

Global Flags:
      --log-flush-frequency duration   Maximum number of seconds between log flushes (default 5s)
      --logging-format string          Sets the log format. Permitted formats: "json" (gated by LoggingBetaOptions), "text". (default "text")
  -v, --v Level                        number for the log level verbosity
      --vmodule pattern=N,...          comma-separated list of pattern=N settings for file-filtered logging (only works for text log format)

👎

The first two lines of help should be:

  1. a one line description of a command
  2. a blank line to indicate that someone understands the contract

Additional paragraphs may be included after the blank line with extended prose, but they should be additional paragraphs not starting at the second line of the output.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions