From ea265a2f9a86e6fc1911041fec4b5fdcefd674dd Mon Sep 17 00:00:00 2001
From: Eric Curtin <eric.curtin@docker.com>
Date: Tue, 20 Oct 2026 18:46:42 +0000
Subject: [PATCH] docs(cli): say --upload cannot take a command (#4502)

Signed-off-by: Eric Curtin <eric.curtin@docker.com>
---
 crates/openshell-cli/src/main.rs          | 33 +++++++++++++++++++++++
 docs/how-it-works/sandboxes/overview.mdx  |  5 ++--
 docs/tutorials/run-pi-with-openrouter.mdx | 10 ++++---
 skills/openshell-cli/SKILL.md             |  1 -
 4 files changed, 42 insertions(+), 7 deletions(-)

diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs
index 4e762c2d1..6e58330ed 100644
--- a/crates/openshell-cli/src/main.rs
+++ b/crates/openshell-cli/src/main.rs
@@ -1472,6 +1472,10 @@ enum SandboxCommands {
         /// Outside a Git work tree, uploads proceed unfiltered with a warning.
         /// Filtering errors or empty selections stop the upload; use
         /// `--no-git-ignore` to intentionally upload everything.
+        ///
+        /// Cannot be combined with a trailing command, because uploads finish
+        /// after the main process starts. Create the sandbox without a command,
+        /// then run the workload with `sandbox exec`.
         #[arg(
             long,
             value_hint = ValueHint::AnyPath,
@@ -4878,6 +4882,35 @@ mod tests {
         );
     }
 
+    #[test]
+    fn sandbox_create_upload_conflicts_with_command_and_help_says_so() {
+        let err = Cli::try_parse_from([
+            "openshell",
+            "sandbox",
+            "create",
+            "--upload",
+            ".",
+            "--",
+            "true",
+        ])
+        .expect_err("--upload with a trailing command should be rejected");
+        assert_eq!(err.kind(), clap::error::ErrorKind::ArgumentConflict);
+
+        let cmd = Cli::command();
+        let create = cmd
+            .find_subcommand("sandbox")
+            .and_then(|c| c.find_subcommand("create"))
+            .expect("missing sandbox create subcommand");
+        let help = create
+            .get_arguments()
+            .find(|a| a.get_id() == "upload")
+            .and_then(|a| a.get_long_help())
+            .expect("--upload has long help")
+            .to_string();
+        assert!(help.contains("Cannot be combined with a trailing command"));
+        assert!(help.contains("sandbox exec"));
+    }
+
     #[test]
     fn sandbox_create_no_git_ignore_requires_upload() {
         let result = Cli::try_parse_from(["openshell", "sandbox", "create", "--no-git-ignore"]);
diff --git a/docs/how-it-works/sandboxes/overview.mdx b/docs/how-it-works/sandboxes/overview.mdx
index 5a8471803..430e90c92 100644
--- a/docs/how-it-works/sandboxes/overview.mdx
+++ b/docs/how-it-works/sandboxes/overview.mdx
@@ -946,10 +946,11 @@ directory are also accepted.
 <Note>
 You can also upload files at creation time with the `--upload` flag on
 `openshell sandbox create`. Pass `--upload` multiple times to upload
-several paths in a single command:
+several paths in a single command. You cannot add a trailing command, so run
+the workload from the shell that opens or with `sandbox exec`:
 
 ```shell
-openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --upload ./src:/workspace/src --upload ./config:/workspace/config -- claude
+openshell sandbox create --from registry.example.com/your-org/claude-agent:latest --upload ./src:/workspace/src --upload ./config:/workspace/config
 ```
 
 </Note>
diff --git a/docs/tutorials/run-pi-with-openrouter.mdx b/docs/tutorials/run-pi-with-openrouter.mdx
index 4e57903f6..b53fc2a68 100644
--- a/docs/tutorials/run-pi-with-openrouter.mdx
+++ b/docs/tutorials/run-pi-with-openrouter.mdx
@@ -185,18 +185,20 @@ blocks. When you're done, type `/quit` in Pi to exit.
 ## Work on a Local Project
 
 To point Pi at your own code, run this from your project directory. `--upload`
-copies the directory into the sandbox before Pi starts, skipping anything
-`.gitignore` excludes.
+copies the directory into the sandbox, skipping anything `.gitignore` excludes.
+You cannot combine `--upload` with a trailing command, so start Pi from the
+shell that opens.
 
 ```shell
 openshell sandbox create \
   --name pi-project \
   --from pi-agent:local \
   --provider openrouter \
-  --upload .:/workspace \
-  -- pi
+  --upload .:/workspace
 ```
 
+In the sandbox shell, run `pi`.
+
 Pi's changes stay inside the sandbox. To copy them back, run
 `openshell sandbox download` from another terminal while Pi is still running.
 Refer to [Transfer Files](/how-it-works/sandboxes/overview#transfer-files).
diff --git a/skills/openshell-cli/SKILL.md b/skills/openshell-cli/SKILL.md
index 8fe37fee1..84e6d65a2 100644
--- a/skills/openshell-cli/SKILL.md
+++ b/skills/openshell-cli/SKILL.md
@@ -291,7 +291,6 @@ openshell sandbox create \
   --provider my-github \
   --provider my-claude \
   --policy ./my-policy.yaml \
-  --upload .:/workspace \
   --label team=agents \
   -- claude
 ```