feat(admin-cli): erase site metadata for a BMC MAC (#3046)

crates/admin-cli/src/machine/erase_metadata/args.rs

@@ -0,0 +1,63 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use clap::Parser;
+use rpc::forge::EraseHostMetadataByBmcMacRequest;
+
+/// Erase all NICo-owned site records for a server BMC MAC address.
+#[derive(Parser, Debug)]
+#[command(after_long_help = "\
+EXAMPLES:
+
+Preview which records exist for a BMC MAC (nothing is deleted):
+    $ nico-admin-cli machine erase-metadata --bmc-mac 00:11:22:33:44:55 --dry-run
+
+Erase all lingering records for a BMC MAC to prepare for re-ingestion:
+    $ nico-admin-cli machine erase-metadata --bmc-mac 00:11:22:33:44:55 --confirm
+
+")]
+pub struct Args {
+    #[clap(
+        long,
+        required(true),
+        help = "Server BMC MAC address whose lingering site records should be erased"
+    )]
+    pub bmc_mac: String,
+
+    #[clap(
+        long,
+        action,
+        help = "Report the records that would be erased without deleting anything"
+    )]
+    pub dry_run: bool,
+
+    #[clap(
+        long,
+        action,
+        help = "Confirm you want to erase these records. Required for a real run (ignored with --dry-run)."
+    )]
+    pub confirm: bool,
+}
+
+impl From<&Args> for EraseHostMetadataByBmcMacRequest {
+    fn from(args: &Args) -> Self {
+        Self {
+            bmc_mac: args.bmc_mac.clone(),
+            dry_run: args.dry_run,
+        }
+    }
+}

crates/admin-cli/src/machine/erase_metadata/cmd.rs

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+use ::rpc::forge::EraseHostMetadataByBmcMacRequest;
+
+use super::args::Args;
+use crate::errors::{CarbideCliError, CarbideCliResult};
+use crate::rpc::ApiClient;
+
+pub async fn erase_metadata(api_client: &ApiClient, args: Args) -> CarbideCliResult<()> {
+    // Guard the destructive path: a real run must be explicitly confirmed. --dry-run
+    // is always safe, so it does not require --confirm. Return an error (non-zero
+    // exit) so scripts can distinguish a refused run from a completed one.
+    if !args.dry_run && !args.confirm {
+        return Err(CarbideCliError::GenericError(format!(
+            "Refusing to erase records for BMC MAC {} without confirmation. \
+             Re-run with --dry-run to preview, or add --confirm to proceed.",
+            args.bmc_mac
+        )));
+    }
+
+    let req: EraseHostMetadataByBmcMacRequest = (&args).into();
+    let response = api_client.0.erase_host_metadata_by_bmc_mac(req).await?;
+
+    if response.dry_run {
+        println!("DRY RUN -- no records were deleted. The following would be erased:");
+    } else {
+        println!("Erased the following records for BMC MAC {}:", args.bmc_mac);
+    }
+    println!("{}", serde_json::to_string_pretty(&response)?);
+
+    Ok(())
+}

crates/admin-cli/src/machine/erase_metadata/mod.rs

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+pub mod args;
+pub mod cmd;
+
+pub use args::Args;
+
+use crate::cfg::run::Run;
+use crate::cfg::runtime::RuntimeContext;
+use crate::errors::CarbideCliResult;
+
+impl Run for Args {
+    async fn run(self, ctx: &mut RuntimeContext) -> CarbideCliResult<()> {
+        cmd::erase_metadata(&ctx.api_client, self).await?;
+        Ok(())
+    }
+}

crates/admin-cli/src/machine/mod.rs

@@ -17,6 +17,7 @@
 
 pub mod auto_update;
 pub mod common;
+pub mod erase_metadata;
 pub mod force_delete;
 pub mod hardware_info;
 pub mod health_report;
@@ -66,6 +67,10 @@ pub enum Cmd {
     Reboot(reboot::Args),
     #[clap(about = "Force delete a machine")]
     ForceDelete(force_delete::Args),
+    #[clap(
+        about = "Erase all NICo-owned site records for a server BMC MAC address (does not touch expected machines)"
+    )]
+    EraseMetadata(erase_metadata::Args),
     #[clap(about = "Set individual machine firmware autoupdate (host only)")]
     AutoUpdate(auto_update::Args),
     #[clap(subcommand, about = "Edit Metadata associated with a Machine")]

crates/admin-cli/src/machine/tests.rs

@@ -360,3 +360,51 @@ fn health_override_templates_value_enum() {
         }
     );
 }
+
+// erase-metadata routes to the EraseMetadata variant. Each row yields
+// (bmc_mac, dry_run, confirm); the required --bmc-mac is missing in the failing row.
+#[test]
+fn parse_erase_metadata_routes_to_erase_metadata() {
+    scenarios!(
+        run = |argv| {
+            Cmd::try_parse_from(argv.iter().copied())
+                .map(|cmd| match cmd {
+                    Cmd::EraseMetadata(args) => (args.bmc_mac, args.dry_run, args.confirm),
+                    _ => panic!("expected EraseMetadata variant"),
+                })
+                .map_err(drop)
+        };
+        "with bmc mac" {
+            &[
+                "machine",
+                "erase-metadata",
+                "--bmc-mac",
+                "00:11:22:33:44:55",
+            ][..] => Yields(("00:11:22:33:44:55".to_string(), false, false)),
+        }
+
+        "with bmc mac and dry-run" {
+            &[
+                "machine",
+                "erase-metadata",
+                "--bmc-mac",
+                "00:11:22:33:44:55",
+                "--dry-run",
+            ][..] => Yields(("00:11:22:33:44:55".to_string(), true, false)),
+        }
+
+        "with bmc mac and confirm" {
+            &[
+                "machine",
+                "erase-metadata",
+                "--bmc-mac",
+                "00:11:22:33:44:55",
+                "--confirm",
+            ][..] => Yields(("00:11:22:33:44:55".to_string(), false, true)),
+        }
+
+        "missing required bmc mac" {
+            &["machine", "erase-metadata"][..] => Fails,
+        }
+    );
+}

crates/api-core/src/api.rs

@@ -1174,6 +1174,13 @@ impl Forge for Api {
         crate::handlers::machine::admin_force_delete_machine(self, request).await
     }
 
+    async fn erase_host_metadata_by_bmc_mac(
+        &self,
+        request: Request<rpc::EraseHostMetadataByBmcMacRequest>,
+    ) -> Result<Response<rpc::EraseHostMetadataByBmcMacResponse>, Status> {
+        crate::handlers::erase_host_metadata::erase_host_metadata_by_bmc_mac(self, request).await
+    }
+
     /// Example TOML data in request.text:
     ///
     /// [lo-ip]

crates/api-core/src/auth/internal_rbac_rules.rs

@@ -290,6 +290,7 @@ impl InternalRBACRules {
         x.perm("FindExploredMlxDeviceHostIds", vec![ForgeAdminCLI]);
         x.perm("FindExploredMlxDevicesByIds", vec![ForgeAdminCLI]);
         x.perm("AdminForceDeleteMachine", vec![ForgeAdminCLI, Machineatron]);
+        x.perm("EraseHostMetadataByBmcMac", vec![ForgeAdminCLI]);
         x.perm("AdminForceDeleteRack", vec![ForgeAdminCLI, Machineatron]);
         x.perm("AdminForceDeleteSwitch", vec![ForgeAdminCLI, Machineatron]);
         x.perm(