diff --git a/docs/reference.md b/docs/reference.md
index 9caed8ea..34238b36 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -3009,6 +3009,41 @@ $> koyeb sandbox expose-port myapp/mysandbox 8080
 
 * [koyeb sandbox](#koyeb-sandbox)	 - Sandbox - interactive execution environments
 
+## koyeb sandbox fs
+
+Filesystem operations
+
+### Options
+
+```
+  -h, --help   help for fs
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string         config file (default is $HOME/.koyeb.yaml)
+  -d, --debug                 enable the debug output
+      --debug-full            do not hide sensitive information (tokens) in the debug output
+      --force-ascii           only output ascii characters (no unicode emojis)
+      --full                  do not truncate output
+      --organization string   organization ID
+  -o, --output output         output format (yaml,json,table)
+      --token string          API token
+      --url string            url of the api (default "https://app.koyeb.com")
+```
+
+
+
+* [koyeb sandbox](#koyeb-sandbox)	 - Sandbox - interactive execution environments
+* [koyeb sandbox fs download](#koyeb-sandbox-fs-download)	 - Download a file from the sandbox
+* [koyeb sandbox fs ls](#koyeb-sandbox-fs-ls)	 - List directory contents in the sandbox
+* [koyeb sandbox fs mkdir](#koyeb-sandbox-fs-mkdir)	 - Create a directory in the sandbox
+* [koyeb sandbox fs read](#koyeb-sandbox-fs-read)	 - Read a file from the sandbox
+* [koyeb sandbox fs rm](#koyeb-sandbox-fs-rm)	 - Remove a file or directory from the sandbox
+* [koyeb sandbox fs upload](#koyeb-sandbox-fs-upload)	 - Upload a local file or directory to the sandbox (max 1G per file)
+* [koyeb sandbox fs write](#koyeb-sandbox-fs-write)	 - Write content to a file in the sandbox
+
 ## koyeb sandbox fs download
 
 Download a file from the sandbox
@@ -3175,6 +3210,11 @@ koyeb sandbox fs rm NAME PATH [flags]
 
 Upload a local file or directory to the sandbox (max 1G per file)
 
+### Synopsis
+
+Upload a local file or directory to the sandbox.
+Parent directories on the sandbox must already exist (create them first with fs mkdir).
+
 ```
 koyeb sandbox fs upload NAME LOCAL_PATH REMOTE_PATH [flags]
 ```
@@ -3212,7 +3252,8 @@ Write content to a file in the sandbox
 ### Synopsis
 
 Write content to a file in the sandbox.
-Content can be provided as an argument or via stdin with -f flag.
+Content can be provided as an argument or from a local file with -f flag.
+Parent directories must already exist (create them first with fs mkdir).
 
 ```
 koyeb sandbox fs write NAME PATH [CONTENT] [flags]
@@ -3255,41 +3296,6 @@ $> koyeb sandbox fs write myapp/mysandbox /tmp/script.py -f ./local-script.py
 
 * [koyeb sandbox fs](#koyeb-sandbox-fs)	 - Filesystem operations
 
-## koyeb sandbox fs
-
-Filesystem operations
-
-### Options
-
-```
-  -h, --help   help for fs
-```
-
-### Options inherited from parent commands
-
-```
-  -c, --config string         config file (default is $HOME/.koyeb.yaml)
-  -d, --debug                 enable the debug output
-      --debug-full            do not hide sensitive information (tokens) in the debug output
-      --force-ascii           only output ascii characters (no unicode emojis)
-      --full                  do not truncate output
-      --organization string   organization ID
-  -o, --output output         output format (yaml,json,table)
-      --token string          API token
-      --url string            url of the api (default "https://app.koyeb.com")
-```
-
-
-
-* [koyeb sandbox](#koyeb-sandbox)	 - Sandbox - interactive execution environments
-* [koyeb sandbox fs download](#koyeb-sandbox-fs-download)	 - Download a file from the sandbox
-* [koyeb sandbox fs ls](#koyeb-sandbox-fs-ls)	 - List directory contents in the sandbox
-* [koyeb sandbox fs mkdir](#koyeb-sandbox-fs-mkdir)	 - Create a directory in the sandbox
-* [koyeb sandbox fs read](#koyeb-sandbox-fs-read)	 - Read a file from the sandbox
-* [koyeb sandbox fs rm](#koyeb-sandbox-fs-rm)	 - Remove a file or directory from the sandbox
-* [koyeb sandbox fs upload](#koyeb-sandbox-fs-upload)	 - Upload a local file or directory to the sandbox (max 1G per file)
-* [koyeb sandbox fs write](#koyeb-sandbox-fs-write)	 - Write content to a file in the sandbox
-
 ## koyeb sandbox health
 
 Check sandbox health status
diff --git a/pkg/koyeb/sandbox.go b/pkg/koyeb/sandbox.go
index 0931d05c..64213a50 100644
--- a/pkg/koyeb/sandbox.go
+++ b/pkg/koyeb/sandbox.go
@@ -202,7 +202,8 @@ $> koyeb sandbox expose-port myapp/mysandbox 8080
 		Use:   "write NAME PATH [CONTENT]",
 		Short: "Write content to a file in the sandbox",
 		Long: `Write content to a file in the sandbox.
-Content can be provided as an argument or via stdin with -f flag.`,
+Content can be provided as an argument or from a local file with -f flag.
+Parent directories must already exist (create them first with fs mkdir).`,
 		Args: cobra.RangeArgs(2, 3),
 		Example: `
 # Write inline content
@@ -249,8 +250,10 @@ $> koyeb sandbox fs write myapp/mysandbox /tmp/script.py -f ./local-script.py
 	fsUploadCmd := &cobra.Command{
 		Use:   "upload NAME LOCAL_PATH REMOTE_PATH",
 		Short: "Upload a local file or directory to the sandbox (max 1G per file)",
-		Args:  cobra.ExactArgs(3),
-		RunE:  WithCLIContext(h.FsUpload),
+		Long: `Upload a local file or directory to the sandbox.
+Parent directories on the sandbox must already exist (create them first with fs mkdir).`,
+		Args: cobra.ExactArgs(3),
+		RunE: WithCLIContext(h.FsUpload),
 	}
 	fsUploadCmd.Flags().BoolP("recursive", "r", false, "Upload directories recursively")
 	fsUploadCmd.Flags().BoolP("force", "f", false, "Overwrite existing remote directory")