adding-beta-subcommand

name	adding-beta-subcommand
description	Use when adding a new beta CLI subcommand to flox, which could also be called an experimental or unstable subcommand. This should be used when adding a command to the `beta` module that respects the `beta` feature flag.

Adding a new beta subcommand

Beta subcommands are top-level flox <name> commands. The Commands::Beta arm in cli/flox/src/commands/mod.rs checks flox.features.beta once before dispatching, so individual handlers shouldn't re-check it.

When not to use this skill

• Adding a subcommand under an existing top-level command (e.g. flox build subcommand). This skill is only for new top-level flox <name> commands gated by features.beta.
• Promoting a beta command to stable — that's a separate move out of the beta module.

Two modules are involved, by design:

• cli/flox/src/beta/ — owns the args struct and handle() body, plus any supporting logic. Plain bpaf-derived structs; no command or hide attributes.
• cli/flox/src/commands/beta.rs — owns the BetaCommands enum where the command name, hide, and dispatch live. This is the reviewed surface that enforces beta commands stay hidden from flox --help.

Steps

1. Create the args + handler in cli/flox/src/beta/<snake_name>.rs. Mirror cli/flox/src/beta/beta_enabled.rs:

   • #[derive(Bpaf, Clone, Debug)] struct holding any options/args.
   • No #[bpaf(command(...))] and no #[bpaf(hide)] on the struct. Those attributes live on the variant in commands/beta.rs.
   • pub async fn handle(self, flox: Flox) -> Result<()> with #[instrument(name = "<command-name>", skip_all)].
   • Do not check flox.features.beta — already gated in the CLI.

2. Register the module in cli/flox/src/beta/mod.rs: pub mod <snake_name>;

3. Wire up the command in cli/flox/src/commands/beta.rs:

   • Add a variant to BetaCommands. Use command("<kebab-name>") and always include hide on the enum variant #[bpaf(hide)] is not sufficient on its own; without per-variant hide the subcommand leaks into flox --help. (Verify with the check in step 4.)

     #[bpaf(command("<kebab-name>"), hide)]
     <CamelName>(#[bpaf(external(<snake_name>::<snake_name>))] <snake_name>::<CamelName>),
     

   • Add a match arm to BetaCommands::handle:

     BetaCommands::<CamelName>(args) => args.handle(flox).await,
     

4. Verify, inside a worktree (per the repo AGENTS.md) and inside nix develop (or wrap each command with nix develop -c if not already in the shell — cargo and friends are not on bare PATH):

   • cargo build -p flox
   • ./target/debug/flox <kebab-name> → exits non-zero with:

     Enable beta features to run this command:
       flox config --set features.beta true
     

   • FLOX_FEATURES_BETA=true ./target/debug/flox <kebab-name> → runs the handler.
   • ./target/debug/flox --help → the new command must not appear. If it does, hide is missing from the variant.

Conventions

• Beta commands may freely depend on flox-rust-sdk, but when adding beta commands, strive to leave flox-rust-sdk code unchanged. Any code in the beta module doesn't need to be reviewed for stability, but any code changes in other crates will require more thorough review which will make it slower to add the beta command.
• Reaching into the rest of the flox crate (crate::utils::message, crate::utils::events, …) is fine and needs no factoring out. Prefer it over duplicating a helper inside beta/.
• Telemetry: beta commands go through the normal dispatcher, so cli.command_run and cli.command_completed are emitted for free — most beta commands need no instrumentation of their own. Add a bespoke v2 event (see the adding-metrics-events skill) only when there is domain data worth reporting; that touches cli/flox-events and is reviewed as a wire-contract change, so the keep-flox-rust-sdk-unchanged guidance above doesn't make it free. Don't add new subcommand_metric! calls — the existing beta commands that use the macro predate the v2 pipeline; don't copy them. Event names are frozen once a release that can emit them ships, gated or not.
• Don't put beta-only logic in commands/, elsewhere in flox, or in flox-rust-sdk; keep it in the beta module.
• Integration tests are not required for beta commands while they remain gated.
• Tests for beta code are skipped by default while the subsystem is gated: cli/tests/extension.bats skips every test from setup(), and unit tests under cli/flox/src/beta/ sit behind the off-by-default beta-tests cargo feature (gate new mod tests with #[cfg(feature = "beta-tests")]). Run them while hacking with cargo test -p flox --features beta-tests beta::.