diff --git a/weed-shell.md b/weed-shell.md
index c4947b5..2d9bc9d 100644
--- a/weed-shell.md
+++ b/weed-shell.md
@@ -308,6 +308,30 @@ Use `-expiry` for time-limited credentials (must be positive; 0 = no expiration)
 `s3.iam.export -file` writes with mode 0600 to protect credentials.
 `s3.iam.import` requires `-apply` since it overwrites the entire IAM configuration.
 
+# Scripting with weed shell
+
+When stdin or stdout is piped, `weed shell` automatically suppresses the `> ` prompt and informational logs, making it easy to use in scripts and parse output with tools like `jq`.
+
+### Heredoc for multiline commands
+```bash
+weed shell << EOF
+lock
+volume.fix.replication -n
+unlock
+EOF
+```
+
+### Pipe JSON output to jq
+```bash
+echo "s3.user.list" | weed shell | jq '.[] | select(.keys > 0)'
+```
+
+### Debug mode
+Use `-debug` to re-enable informational logs on stderr:
+```bash
+echo "s3.user.list" | weed shell -debug 2>shell.log | jq
+```
+
 # One more trick
 You can skip the "fs." prefix, for all "fs.*" commands:
 ```