RegisterCommand plugins still resolve too late for top-level `nix <plugin-cmd>` (2.36)

[mikenrafter]

Summary

plugin-files / RegisterCommand is documented as the way to add nix subcommands (man nix.conf, manual). On current CppNix (reproduced on 2.36pre20260912_203f85b2), a plugin that registers a top-level command is visible in nix --help and NIX_GET_COMPLETIONS, but nix <cmd> … fails with '<cmd>' is not a recognised command.

This is the same class of bug as #2597 / the intent of #4486, still present on master.

Reproduction

1. Build a trivial RegisterCommand("scout") plugin (or any name) against the running nix / nix-cmd ABI.
2. Load it without any PATH wrapper:

NIX_CONFIG="plugin-files = /path/to/nix-scout.so" nix --help | grep scout
# → · nix scout - …

NIX_GET_COMPLETIONS=1 NIX_CONFIG="plugin-files = …" nix '' | grep scout
# → scout is offered

NIX_CONFIG="plugin-files = …" nix scout --help
# → error: 'scout' is not a recognised command

Cause

In RootArgs::parseCmdline (src/libutil/args.cc), the first non-flag argument is handled via MultiCommand::processArgs, which looks up the subcommand in the pre-plugin command map and throws if missing.

initialFlagsProcessed() → initPlugins() → pluginsInited() (which refreshes commands = RegisterCommand::getCommandsFor({}) in src/nix/main.cc) runs only after the entire cmdline has been parsed.

That contradicts the comment on Args::initialFlagsProcessed() in args.hh (“Called after all command line flags before the first non-flag argument”) and the design from #4486 (load plugins after initial flags, then resolve the subcommand).

Expected

With plugin-files set in nix.conf (or as an initial flag before the subcommand), nix <plugin-cmd> … should dispatch to the plugin-registered command, matching the documented RegisterCommand API.

Related

• Cannot RegisterCommand from a plugin #2597 (still open)
• Command plugins #4486 / Add support for plugins that provide a new subcommand #2600 (earlier fixes for command plugins)
• Workaround used in the wild: a hiPrio PATH nix wrapper that intercepts the subcommand before invoking the real binary

[mikenrafter]

I published a standalone reproducer pinned to 2.36pre20260912_203f85b2:

https://github.com/mikenrafter/nix-register-command-repro

nix run .#reproduce demonstrates all three cases:

1. plugin-files makes subcmdtest appear in nix --help.
2. nix subcmdtest fails with 'subcmdtest' is not a recognised command.
3. Loading the identical shared object before main() makes nix subcmdtest print test successful!.

The flake also checks that the plugin has no libnix* DT_NEEDED entries and builds against the pinned nix-cmd headers. nix flake check passes.

[xokdvium]

Hm, thanks. This seems to have been broken in 39a2696 accidentally. @cole-h cc

[xokdvium]

God it's such a mess. Making this work properly with all the various ways to specify settings (namely cli or in NIX_CONFIG/files) is going to be a pain. It would be so much nicer if we actually passed settings around as references instead of just blindly mucking with globals.

[xokdvium]

Maybe it would make more sense to separate out the different phases:

1. Grab plugin-files from all the settings / cli without applying them or mutating anything.
2. Only load plugins as extracted from the various ways one might configure that.
3. Do the actual parsing and apply side effects.

That would be a bit more obviously correct.

[mikenrafter]

I told my agent "look at the issue and implement what @xokdvium suggests".
nix-register-command-before-subcommand.patch
Seems to work.

[mikenrafter]

I'm not typically in C. Is this gist worth nurturing or refactoring or does it make too much a mess of the area? I'm willing to dig in a bit here and make a PR if I know the general direction is right at least.

[xokdvium]

I think this approach is the best bet for now. Ideally I'd have us rip up how settings are initialised more and bring some sanity into it, but this feels like a worthwhile hack for now. I also have some tests for this locally to cover various ways to specify plugins. I can take over + add those tests if you want to get a branch up.

[mikenrafter]

Here's a branch: nix-register-command-before-subcommand.