Summary
The current drenv help output provides the command syntax, but some commands have only a short description and no usage examples. This makes it difficult for new users to understand when to use a command and how it differs from related commands.
This issue proposes improving the help text by adding longer descriptions and examples where they provide additional value.
Example of some commands with proposed help improvements
start
Why?
- not clear that we need to run
setup before this.
- more info on what the command does
setup
Why?
setup is frequently confused with start. The help text should explain the responsibilities of setup and how it differs from start.
delete
Why?
- more info on what the command does
Proposed help output
The current help text for each command can be generated using:
The proposed help text can then extend the existing output with:
- A more detailed description explaining the purpose of the command.
- One or more common usage examples.
- Notes describing when the command should be used relative to other
drenv commands.
start
Current text
% drenv start -h
usage: drenv start [-h] [--logfile LOGFILE] [--name-prefix PREFIX] [--skip-tests] [--skip-addons]
[--max-workers N] [--timeout TIMEOUT] [--local-registry] [--dns-mode {auto,static,host}]
envfile
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
--skip-tests Do not run addons 'test' hooks
--skip-addons Do not run addons 'start' hooks
--max-workers N maximum number of workers per profile
--timeout TIMEOUT time in seconds to wait until clsuter is started
--local-registry Use local registry. For lima provider the local registry must have the k8s images for
kubeadm. See registry/README.md for more info.
--dns-mode {auto,static,host}
DNS configuration mode. 'auto' detects managed Macs and uses 'static' if needed.
'static' configures public DNS servers (8.8.8.8, 1.1.1.1). 'host' uses the host resolver
(default for minikube, may not work on managed Macs).New help text
% drenv start -h
usage: drenv start [-h] [--logfile LOGFILE] [--name-prefix PREFIX] [--skip-tests] [--skip-addons]
[--max-workers N] [--timeout TIMEOUT] [--local-registry] [--dns-mode {auto,static,host}]
envfile
Start the DR environment defined in the envfile. Creates minikube clusters for each profile (if they don't
already exist), deploys all addons, and runs addon tests. The command is idempotent — rerunning it on an
already-running environment is safe. Run drenv setup once before the first start to prepare the host.
Examples:
# Start the regional-dr.yaml environemnt
drenv start test/envs/regional-dr.yaml
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
--skip-tests Do not run addons 'test' hooks
--skip-addons Do not run addons 'start' hooks
--max-workers N maximum number of workers per profile
--timeout TIMEOUT time in seconds to wait until clsuter is started
--local-registry Use local registry. For lima provider the local registry must have the k8s images for
kubeadm. See registry/README.md for more info.
--dns-mode {auto,static,host}
DNS configuration mode. 'auto' detects managed Macs and uses 'static' if needed.
'static' configures public DNS servers (8.8.8.8, 1.1.1.1). 'host' uses the host resolver
(default for minikube, may not work on managed Macs).setup
Current text
% drenv setup -h
usage: drenv setup [-h] [--logfile LOGFILE] [--name-prefix PREFIX] envfile
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
New help text
% drenv setup -h
usage: drenv setup [-h] [--logfile LOGFILE] [--name-prefix PREFIX] envfile
Prepare the host for the DR environment defined in the envfile. Installs and configures
the host-level dependencies required by the environment. This command does not create or
start any clusters and typically needs to be run only once before the first `drenv start`.
Examples:
# Prepare the host for the regional-dr environment
drenv setup test/envs/regional-dr.yaml
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
delete
Current text
% drenv delete -h
usage: drenv delete [-h] [--logfile LOGFILE] [--name-prefix PREFIX] envfile
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
New help text
% drenv delete -h
usage: drenv delete [-h] [--logfile LOGFILE] [--name-prefix PREFIX] envfile
Delete the DR environment defined in the envfile. Removes the clusters and associated
resources created for the environment. Use this command to clean up an environment after
testing or before recreating it from scratch.
Examples:
# Delete the regional-dr environment
drenv delete test/envs/regional-dr.yaml
positional arguments:
envfile path to environment file
options:
-h, --help show this help message and exit
--logfile LOGFILE path to logfile (default 'drenv.log')
--name-prefix PREFIX prefix profile names
Summary
The current
drenvhelp output provides the command syntax, but some commands have only a short description and no usage examples. This makes it difficult for new users to understand when to use a command and how it differs from related commands.This issue proposes improving the help text by adding longer descriptions and examples where they provide additional value.
Example of some commands with proposed help improvements
startWhy?
setupbefore this.setupWhy?
setupis frequently confused withstart. The help text should explain the responsibilities ofsetupand how it differs fromstart.deleteWhy?
Proposed help output
The current help text for each command can be generated using:
The proposed help text can then extend the existing output with:
drenvcommands.start
Current text
New help text
setup
Current text
New help text
delete
Current text
New help text