diff --git a/crates/nu-cmd-lang/src/core_commands/def.rs b/crates/nu-cmd-lang/src/core_commands/def.rs
index eb1124da19..e4a169ffcc 100644
--- a/crates/nu-cmd-lang/src/core_commands/def.rs
+++ b/crates/nu-cmd-lang/src/core_commands/def.rs
@@ -60,6 +60,11 @@ impl Command for Def {
                 example: r#"def --env foo [] { $env.BAR = "BAZ" }; foo; $env.BAR"#,
                 result: Some(Value::test_string("BAZ")),
             },
+            Example {
+                description: "cd affects the environment, so '--env' is required to change directory from within a command",
+                example: r#"def --env gohome [] { cd ~ }; gohome; $env.PWD == ('~' | path expand)"#,
+                result: Some(Value::test_string("true")),
+            },
             Example {
                 description: "Define a custom wrapper for an external command",
                 example: r#"def --wrapped my-echo [...rest] { echo $rest }; my-echo spam"#,
diff --git a/crates/nu-command/src/filesystem/cd.rs b/crates/nu-command/src/filesystem/cd.rs
index 57fe1c17e3..4e09d900d2 100644
--- a/crates/nu-command/src/filesystem/cd.rs
+++ b/crates/nu-command/src/filesystem/cd.rs
@@ -135,6 +135,11 @@ impl Command for Cd {
                 example: r#"cd -"#,
                 result: None,
             },
+            Example {
+                description: "Changing directory with a custom command requires 'def --env'",
+                example: r#"def --env gohome [] { cd ~ }"#,
+                result: None,
+            },
         ]
     }
 }