From 4d74795dd2dd8ecf58b06ce87c8fddb2f0c93382 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Wed, 8 Apr 2026 12:16:36 -0700
Subject: [PATCH] docs(weed-shell): add scripting section with heredoc, piping,
 and -debug flag

---
 weed-shell.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

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:
 ```