new command: unlet (#17270)

Presenting a new command `unlet` that will delete variables from the
nushell memory. I'm not sure how acutally useful this is but I thought
it would be fun to play around and see if it's useful. I don't really
like the name but it says what it does so that counts for something.

I also kind of see this as a tiny first step toward some type of garbage
collection.

<img width="1907" height="681" alt="image"
src="https://github.com/user-attachments/assets/a4caffab-4ef8-447e-a3ed-8c2e7256aaaa"
/>

nushell's internal variables like `$in`, `$env`, `$nu` are protected
from deletion.

Feel free to take it for a spin and let me know if it's trash.

## Release notes summary - What our users need to know
The new command `unlet` will delete variables from memory.

## Tasks after submitting
N/A

Author: fdncred

crates/nu-command/src/default_context.rs

@@ -97,6 +97,7 @@ pub fn add_shell_command_context(mut engine_state: EngineState) -> EngineState {
 
         // Misc
         bind_command! {
+            DeleteVar,
             Panic,
             Source,
             Tutor,

crates/nu-command/src/misc/mod.rs

@@ -1,7 +1,9 @@
 mod panic;
 mod source;
 mod tutor;
+mod unlet;
 
 pub use panic::Panic;
 pub use source::Source;
 pub use tutor::Tutor;
+pub use unlet::DeleteVar;

crates/nu-command/src/misc/unlet.rs

@@ -0,0 +1,128 @@
+use nu_engine::command_prelude::*;
+use nu_protocol::engine::{ENV_VARIABLE_ID, IN_VARIABLE_ID, NU_VARIABLE_ID};
+
+#[derive(Clone)]
+pub struct DeleteVar;
+
+impl Command for DeleteVar {
+    fn name(&self) -> &str {
+        "unlet"
+    }
+
+    fn description(&self) -> &str {
+        "Delete variables from nushell memory, making them unrecoverable."
+    }
+
+    fn signature(&self) -> nu_protocol::Signature {
+        Signature::build("unlet")
+            .input_output_types(vec![(Type::Nothing, Type::Nothing)])
+            .rest(
+                "rest",
+                SyntaxShape::Any,
+                "The variables to delete (pass as $variable_name).",
+            )
+            .category(Category::Experimental)
+    }
+
+    fn run(
+        &self,
+        _engine_state: &EngineState,
+        stack: &mut Stack,
+        call: &Call,
+        _input: PipelineData,
+    ) -> Result<PipelineData, ShellError> {
+        // Collect all positional arguments passed to the command
+        let expressions: Vec<_> = (0..).map_while(|i| call.positional_nth(stack, i)).collect();
+
+        // Ensure at least one argument is provided
+        if expressions.is_empty() {
+            return Err(ShellError::GenericError {
+                error: "Wrong number of arguments".into(),
+                msg: "unlet takes at least one argument".into(),
+                span: Some(call.head),
+                help: None,
+                inner: vec![],
+            });
+        }
+
+        // Validate each argument and collect valid variable IDs
+        let mut var_ids = Vec::with_capacity(expressions.len());
+        for expr in expressions {
+            match &expr.expr {
+                nu_protocol::ast::Expr::Var(var_id) => {
+                    // Prevent deletion of built-in variables that are essential for nushell operation
+                    if var_id == &NU_VARIABLE_ID
+                        || var_id == &ENV_VARIABLE_ID
+                        || var_id == &IN_VARIABLE_ID
+                    {
+                        // Determine the variable name for the error message
+                        let var_name = match *var_id {
+                            NU_VARIABLE_ID => "nu",
+                            ENV_VARIABLE_ID => "env",
+                            IN_VARIABLE_ID => "in",
+                            _ => "unknown", // This should never happen due to the check above
+                        };
+
+                        return Err(ShellError::GenericError {
+                            error: "Cannot delete built-in variable".into(),
+                            msg: format!(
+                                "'${}' is a built-in variable and cannot be deleted",
+                                var_name
+                            ),
+                            span: Some(expr.span),
+                            help: None,
+                            inner: vec![],
+                        });
+                    }
+                    var_ids.push(*var_id);
+                }
+                _ => {
+                    // Argument is not a variable reference
+                    return Err(ShellError::GenericError {
+                        error: "Not a variable".into(),
+                        msg: "Argument must be a variable reference like $x".into(),
+                        span: Some(expr.span),
+                        help: Some("Use $variable_name to refer to the variable".into()),
+                        inner: vec![],
+                    });
+                }
+            }
+        }
+
+        // Remove all valid variables from the stack
+        for var_id in var_ids {
+            stack.remove_var(var_id);
+        }
+
+        Ok(PipelineData::empty())
+    }
+
+    fn requires_ast_for_arguments(&self) -> bool {
+        true
+    }
+
+    fn examples(&self) -> Vec<Example<'_>> {
+        vec![
+            Example {
+                example: "let x = 42; unlet $x",
+                description: "Delete a variable from memory",
+                result: None,
+            },
+            Example {
+                example: "let x = 1; let y = 2; unlet $x $y",
+                description: "Delete multiple variables from memory",
+                result: None,
+            },
+            Example {
+                example: "unlet $nu",
+                description: "Attempting to delete a built-in variable fails",
+                result: None,
+            },
+            Example {
+                example: "unlet 42",
+                description: "Attempting to delete a non-variable fails",
+                result: None,
+            },
+        ]
+    }
+}

crates/nu-command/tests/commands/mod.rs

@@ -119,6 +119,7 @@ mod try_;
 mod ucp;
 #[cfg(unix)]
 mod ulimit;
+mod unlet;
 mod window;
 
 mod debug;

crates/nu-command/tests/commands/unlet.rs

@@ -0,0 +1,54 @@
+use nu_test_support::nu;
+
+#[test]
+fn unlet_basic() {
+    let actual = nu!("let x = 42; unlet $x; $x");
+
+    assert!(actual.err.contains("Variable not found"));
+}
+
+#[test]
+fn unlet_builtin_nu() {
+    let actual = nu!("unlet $nu");
+
+    assert!(actual.err.contains("cannot be deleted"));
+}
+
+#[test]
+fn unlet_builtin_env() {
+    let actual = nu!("unlet $env");
+
+    assert!(actual.err.contains("cannot be deleted"));
+}
+
+#[test]
+fn unlet_not_variable() {
+    let actual = nu!("unlet 42");
+
+    assert!(
+        actual
+            .err
+            .contains("Argument must be a variable reference like $x")
+    );
+}
+
+#[test]
+fn unlet_wrong_number_args() {
+    let actual = nu!("unlet");
+
+    assert!(actual.err.contains("unlet takes at least one argument"));
+}
+
+#[test]
+fn unlet_multiple_args() {
+    let actual = nu!("let x = 1; let y = 2; unlet $x $y; $x");
+
+    assert!(actual.err.contains("Variable not found"));
+}
+
+#[test]
+fn unlet_multiple_deletes_both() {
+    let actual = nu!("let x = 1; let y = 2; unlet $x $y; $y");
+
+    assert!(actual.err.contains("Variable not found"));
+}

crates/nu-engine/src/compile/call.rs

@@ -3,7 +3,7 @@ use std::sync::Arc;
 use nu_protocol::{
     IntoSpanned, RegId, Span, Spanned,
     ast::{Argument, Call, Expression, ExternalArgument},
-    engine::StateWorkingSet,
+    engine::{ENV_VARIABLE_ID, IN_VARIABLE_ID, NU_VARIABLE_ID, StateWorkingSet},
     ir::{Instruction, IrAstRef, Literal},
 };
 
@@ -77,6 +77,11 @@ pub(crate) fn compile_call(
         }
     }
 
+    // Special handling for builtin commands that have direct IR equivalents
+    if decl.name() == "unlet" {
+        return compile_unlet(working_set, builder, call, io_reg);
+    }
+
     // Keep AST if the decl needs it.
     let requires_ast = decl.requires_ast_for_arguments();
 
@@ -270,3 +275,85 @@ pub(crate) fn compile_external_call(
 
     compile_call(working_set, builder, &call, redirect_modes, io_reg)
 }
+
+pub(crate) fn compile_unlet(
+    _working_set: &StateWorkingSet,
+    builder: &mut BlockBuilder,
+    call: &Call,
+    io_reg: RegId,
+) -> Result<(), CompileError> {
+    // unlet takes one or more positional arguments which should be variable references
+    if call.positional_len() == 0 {
+        return Err(CompileError::InvalidLiteral {
+            msg: "unlet takes at least one argument".into(),
+            span: call.head,
+        });
+    }
+
+    // Process each positional argument
+    for i in 0..call.positional_len() {
+        let Some(arg) = call.positional_nth(i) else {
+            return Err(CompileError::InvalidLiteral {
+                msg: "Expected positional argument".into(),
+                span: call.head,
+            });
+        };
+
+        // Extract variable ID from the expression
+        // Handle both direct variable references (Expr::Var) and full cell paths (Expr::FullCellPath)
+        // that represent simple variables (e.g., $var parsed as FullCellPath with empty tail).
+        // This allows unlet to work with variables parsed in different contexts.
+        let var_id = match &arg.expr {
+            nu_protocol::ast::Expr::Var(var_id) => Some(*var_id),
+            nu_protocol::ast::Expr::FullCellPath(cell_path) => {
+                if cell_path.tail.is_empty() {
+                    match &cell_path.head.expr {
+                        nu_protocol::ast::Expr::Var(var_id) => Some(*var_id),
+                        _ => None,
+                    }
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        };
+
+        match var_id {
+            Some(var_id) => {
+                // Prevent deletion of built-in variables that are essential for nushell operation
+                if var_id == NU_VARIABLE_ID || var_id == ENV_VARIABLE_ID || var_id == IN_VARIABLE_ID
+                {
+                    // Determine the variable name for the error message
+                    let var_name = match var_id {
+                        NU_VARIABLE_ID => "nu",
+                        ENV_VARIABLE_ID => "env",
+                        IN_VARIABLE_ID => "in",
+                        _ => "unknown", // This should never happen due to the check above
+                    };
+
+                    return Err(CompileError::InvalidLiteral {
+                        msg: format!(
+                            "'${}' is a built-in variable and cannot be deleted",
+                            var_name
+                        ),
+                        span: arg.span,
+                    });
+                }
+
+                // Emit instruction to drop the variable
+                builder.push(Instruction::DropVariable { var_id }.into_spanned(call.head))?;
+            }
+            None => {
+                // Argument is not a valid variable reference
+                return Err(CompileError::InvalidLiteral {
+                    msg: "Argument must be a variable reference like $x".into(),
+                    span: arg.span,
+                });
+            }
+        }
+    }
+
+    // Load empty value as the result
+    builder.load_empty(io_reg)?;
+    Ok(())
+}

crates/nu-engine/src/scope.rs

@@ -57,9 +57,15 @@ impl<'e, 's> ScopeData<'e, 's> {
             let var_type = Value::string(var.ty.to_string(), span);
             let is_const = Value::bool(var.const_val.is_some(), span);
 
-            let var_value = self
-                .stack
-                .get_var(**var_id, span)
+            let var_value_result = self.stack.get_var(**var_id, span);
+
+            // Skip variables that have no value in the stack and are not constants.
+            // This ensures that variables deleted with unlet disappear from scope variables.
+            if var_value_result.is_err() && var.const_val.is_none() {
+                continue;
+            }
+
+            let var_value = var_value_result
                 .ok()
                 .or(var.const_val.clone())
                 .unwrap_or(Value::nothing(span));