From 3562b71a0a554ae7588ab83388f4e342f04deb00 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 13 Aug 2026 14:15:31 +0000 Subject: [PATCH] docs(run): document that scripts and commands run from the project root `devbox run` always executes from the directory containing devbox.json (cmd.Dir is set to the project dir in nix.RunScript), regardless of the subdirectory the command is invoked from. This surprises users who expect the current working directory to be respected, as reported in #2559. A maintainer confirmed the behavior is intentional so that a command run via `devbox run -- ` behaves consistently with a script defined in devbox.json. The reporter's follow-up ask was simply to surface this in the command help. Add a short paragraph to the `devbox run` long help explaining the working-directory behavior and how to run from a subdirectory. Closes #2559 --- internal/boxcli/run.go | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/internal/boxcli/run.go b/internal/boxcli/run.go index 12da7b7d855..44d37a4d068 100644 --- a/internal/boxcli/run.go +++ b/internal/boxcli/run.go @@ -48,7 +48,11 @@ func runCmd(defaults runFlagDefaults) *cobra.Command { Long: "Start a new shell and runs your script or command in it, exiting when done.\n\n" + "The script must be defined in `devbox.json`, or else it will be interpreted as an " + "arbitrary command. You can pass arguments to your script or command. Everything " + - "after `--` will be passed verbatim into your command (see examples).\n\n", + "after `--` will be passed verbatim into your command (see examples).\n\n" + + "Scripts and commands always run from the project's root directory (the directory " + + "containing your `devbox.json`), not the current working directory. If you invoke " + + "`devbox run` from a subdirectory and need to run there, change into it as part of " + + "your command, e.g. `devbox run -- sh -c 'cd subdir && '`.\n\n", Example: "\nRun a command directly:\n\n devbox add cowsay\n devbox run cowsay hello\n " + "devbox run -- cowsay -d hello\n\nRun a script (defined as `\"moo\": \"cowsay moo\"`) " + "in your devbox.json:\n\n devbox run moo",