CLI: allow augur --help to run without DB configuration by mezo78902 · Pull Request #3661 · chaoss/augur

mezo78902 · 2026-02-08T13:28:53Z

augur --help previously triggered eager imports of CLI command modules via click.MultiCommand.get_command(), which could initialize DB/config and exit before rendering help.

This change returns a lightweight lazy proxy command from get_command(), importing the actual command module only when invoked. short_help is parsed from command source as a best-effort to keep the top-level help informative without importing modules.

Scope is intentionally limited to a single file: augur/application/cli/_multicommand.py. Runtime behavior for actual command execution remains unchanged.

mezo78902 · 2026-02-08T13:55:08Z

@MoralCode I opened a new minimal PR (#3661) that only changes _multicommand.py to lazy-load commands so augur --help works without DB config.

MoralCode · 2026-02-08T15:42:14Z

@MoralCode I opened a new minimal PR (#3661) that only changes _multicommand.py to lazy-load commands so augur --help works without DB config.

yep, thats this PR, thanks!

MoralCode · 2026-02-08T15:44:13Z

Can you provide some more detail on why this change was needed? this feels like a very structural change to the object that seems to be underlying almost every CLI command.

Was it the importing of this module that is dependent on the database?

mezo78902 · 2026-02-08T16:00:11Z

Can you provide some more detail on why this change was needed? this feels like a very structural change to the object that seems to be underlying almost every CLI command.

Was it the importing of this module that is dependent on the database?

Great question — _multicommand.py itself is not database-dependent.

The issue is that Click builds the help output by calling get_command() for every command.
Before this change, get_command() eagerly imported each command module just to retrieve the command object and short_help.

Some of those command modules have import-time side effects or transitive imports that touch database or config logic, so augur --help could fail before any output was rendered in a fresh environment.

This change only defers importing the command module until the command is actually invoked.
Runtime behavior for augur <command> is unchanged — failures still occur at execution time if configuration is missing.

The change is isolated to CLI wiring and avoids touching DB, Redis, or runtime logic.

MoralCode · 2026-02-09T03:12:04Z

Some of those command modules have import-time side effects or transitive imports that touch database or config logic, so augur --help could fail before any output was rendered in a fresh environment.

Do you have a sense of how much of the CLI is impacted by this? if its only a couple files maybe its worth adjusting how the imports are structured so that click can do its job as intended.

mezo78902 · 2026-02-09T04:32:56Z

Some of those command modules have import-time side effects or transitive imports that touch database or config logic, so augur --help could fail before any output was rendered in a fresh environment.

Do you have a sense of how much of the CLI is impacted by this? if its only a couple files maybe its worth adjusting how the imports are structured so that click can do its job as intended.

I actually just tested that exact approach by refactoring backend.py to move all top-level imports (tasks, celery, KeyClient) into local function scope. augur --help still failed with the same DB error.

That suggests the issue is transitive and affects more than a couple of files—importing one CLI module often pulls in others that eagerly touch DB/config at import time.

Refactoring imports file-by-file would likely turn into whack-a-mole. The lazy proxy approach here provides a safer, structural boundary that ensures --help works without impacting runtime behavior.

mezo78902 · 2026-02-10T16:21:43Z

Hi @MoralCode
I tried a simpler approach that might better fit your concern about structural changes.
During top-level --help, get_command() returns a small placeholder command so help can render without importing modules.
Execution behavior stays exactly the same otherwise.

Happy to update the PR this way if that sounds reasonable.

MoralCode · 2026-02-11T14:24:35Z

augur/application/cli/_multicommand.py

+    def _load(self) -> click.Command:
+        if self._real_cmd is None:
+            module = importlib.import_module(self._import_name)
+            self._real_cmd = module.cli
+        return self._real_cmd
+
+    def _proxy_callback(self, *args, **kwargs):
+        # If click ends up calling callback directly, delegate
+        return self._load().callback(*args, **kwargs)
+
+    def invoke(self, ctx):
+        return self._load().invoke(ctx)
+
+    def get_params(self, ctx):
+        return self._load().get_params(ctx)
+
+    def get_help(self, ctx):
+        return self._load().get_help(ctx)


this still seems like it is effectively using importlib to import the command modules. I dont think this is likely to work since theres a lot of database dependencies at import time :/

MoralCode · 2026-02-11T14:26:45Z

Id be curious to know whether click is doing any kind of intelligent generation of the help text based on things other than the short_help arg that you seem to be targeting in this PR (i suspect it does)

Having a demo of what your code outputs for the help text would also be nice to have as a proof of concept

Im worried there may not be a good solution here besides fixing the underlying "database connection needed at import time" issue, which is a very major change

mezo78902 · 2026-02-12T12:17:47Z

Thanks — you’re right about the proxy still importing. I haven’t pushed the placeholder approach yet; I just tested it locally. I’ll update this PR to the placeholder-only-for-top-level-help version (no imports during augur --help, no short_help parsing) and add the demo output.

MoralCode · 2026-02-12T14:13:47Z

no imports during augur --help, no short_help parsing

is this going to make the help text less useful?

mezo78902 · 2026-02-12T16:36:23Z

no imports during augur --help, no short_help parsing

is this going to make the help text less useful?

A little, yes — it may be a little less informative because we’d lose the per-command short_help lines in the top-level listing.
But it still shows Usage, options, and the full command list, which is the main onboarding need.
If we want to restore summaries later without imports, we could add a small static registry, but I’d prefer keeping this PR minimal for now.

mezo78902 · 2026-02-12T16:47:38Z

Just to clarify — I haven’t pushed the placeholder-based update yet. The current PR still reflects the lazy proxy implementation.

Before updating the PR, I’d really appreciate your perspective — do you feel that omitting short_help is an acceptable tradeoff for ensuring --help works reliably without DB configuration?

MoralCode · 2026-02-12T19:16:32Z

Before updating the PR, I’d really appreciate your perspective — do you feel that omitting short_help is an acceptable tradeoff for ensuring --help works reliably without DB configuration?

yeah lets do that. its not ideal but having a dynamic list of all the commands that exist is probably more helpful

The other option is to put a copy of the help output in the docs somewhere as a workaround and tackle the long term solution to this at once (but i worry we will forget to follow up on that.

In addition to moving ahead on this, id be curious how possible you think it might be to use AST-like methods to parse through the files to recover the short_help and re-attach them to their relevant help items. I suspect this should be a separate PR though

mezo78902 · 2026-02-13T21:15:32Z

Hi @MoralCode,

I’ve updated the PR to use the simpler placeholder-only approach we discussed.

During top-level augur --help, get_command() now returns a minimal click.Command(name=...) so that help can render without importing any command modules. No imports occur during help generation.

The normal execution path for augur remains unchanged — modules are still imported at invocation time as before.

As agreed, this version intentionally omits per-command short_help lines in the top-level listing to avoid any import-time side effects.

Here is the output in a fresh environment with no DB configuration:

$ augur --help
Usage: augur [OPTIONS] COMMAND [ARGS]...

Augur is an application for open source community health analytics

Options:
--help Show this message and exit.

Commands:
api
backend
cache
collection
config
csv_utils
db
github
jumpstart
tasks
user

Please let me know if this aligns better with your expectations. I’d be happy to explore an AST-based approach for restoring short_help in a separate follow-up PR.

MoralCode · 2026-02-13T22:15:52Z

It may be worth including a message in this limited output To explain that the output is intentionally limited because there's no database access available and linking to the issue.

Augur is an application for open source community health analytics Options: --help Show this message and exit. Commands: api Commands for controlling the backend API server backend Commands for controlling the backend API server & data collection workers cache Commands for managing redis cache collection Commands for controlling the backend API server & data collection workers config Generate an augur.config.json csv_utils db Database utilities github Github utilities jumpstart tasks Commands for controlling the backend API server & data collection workers user Support for adding regular users or administrative users works without DB config Signed-off-by: Hamza <mezohafez1@gmail.com>

mezo78902 · 2026-02-13T22:24:00Z

Thanks for the suggestion — I’ve added a brief note to the help output explaining that it is intentionally limited when no database configuration is available, and linked to #3654 for context.

Please let me know if this wording looks appropriate.

mezo78902 force-pushed the fix/cli-help-no-db-minimal branch from e0c3977 to ecef22b Compare February 8, 2026 13:31

mezo78902 changed the title ~~Lazy-load CLI commands so Usage: augur [OPTIONS] COMMAND [ARGS]...~~ Lazy-load CLI commands so augur --help works without DB config Feb 8, 2026

mezo78902 mentioned this pull request Feb 8, 2026

CLI: allow bootstrap commands to run without DB configuration #3658

Closed

MoralCode reviewed Feb 11, 2026

View reviewed changes

MoralCode added the CLI Related to Augur's CLI label Feb 13, 2026

mezo78902 force-pushed the fix/cli-help-no-db-minimal branch from ecef22b to ceea310 Compare February 13, 2026 21:04

mezo78902 changed the title ~~Lazy-load CLI commands so augur --help works without DB config~~ CLI: allow augur --help to run without DB configuration Feb 13, 2026

mezo78902 force-pushed the fix/cli-help-no-db-minimal branch from ceea310 to d26c6a4 Compare February 13, 2026 22:22

mezo78902 requested a review from MoralCode February 24, 2026 07:37

Conversation

mezo78902 commented Feb 8, 2026

Uh oh!

mezo78902 commented Feb 8, 2026

Uh oh!

MoralCode commented Feb 8, 2026

Uh oh!

MoralCode commented Feb 8, 2026

Uh oh!

mezo78902 commented Feb 8, 2026

Uh oh!

MoralCode commented Feb 9, 2026

Uh oh!

mezo78902 commented Feb 9, 2026

Uh oh!

mezo78902 commented Feb 10, 2026

Uh oh!

MoralCode Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

MoralCode commented Feb 11, 2026

Uh oh!

mezo78902 commented Feb 12, 2026

Uh oh!

MoralCode commented Feb 12, 2026

Uh oh!

mezo78902 commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mezo78902 commented Feb 12, 2026

Uh oh!

MoralCode commented Feb 12, 2026

Uh oh!

mezo78902 commented Feb 13, 2026

Uh oh!

MoralCode commented Feb 13, 2026

Uh oh!

mezo78902 commented Feb 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mezo78902 commented Feb 12, 2026 •

edited

Loading