From 6d0a7b031f2d12a8f6f30d6a12cec0a82c452b78 Mon Sep 17 00:00:00 2001
From: Chris Lu <chris.lu@gmail.com>
Date: Tue, 7 Apr 2026 14:12:44 -0700
Subject: [PATCH] docs: update shell IAM docs for review-driven changes

- s3.iam.import now requires -force flag
- s3.iam.export -file writes with mode 0600
- s3.anonymous.set validates and normalizes actions (case-insensitive)
- s3.serviceaccount.create validates actions and rejects negative expiry
- s3.user.provision rejects wildcards and checks user existence first
---
 weed-shell.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/weed-shell.md b/weed-shell.md
index f038507..4228bf5 100644
--- a/weed-shell.md
+++ b/weed-shell.md
@@ -261,6 +261,9 @@ Access Key: AKID...
 Secret Key: ...
 ```
 
+Roles: `readonly`, `readwrite`, `admin`. The bucket must be a literal name (no wildcards).
+If the user already exists, the command fails without creating an orphaned policy.
+
 ### Manage credentials
 ```
 > s3.accesskey.create -user alice
@@ -276,14 +279,21 @@ Secret Key: ...
 > s3.anonymous.list
 ```
 
+Actions are validated and case-insensitive (`read` and `Read` both work).
+Supported actions: Read, Write, List, Tagging, Admin.
+
 ### Manage service accounts
 ```
 > s3.serviceaccount.create -user alice -description "CI pipeline" -actions Read,List
+> s3.serviceaccount.create -user alice -expiry 24h
 > s3.serviceaccount.list -user alice
 > s3.serviceaccount.show -id sa-xxxxx
 > s3.serviceaccount.delete -id sa-xxxxx
 ```
 
+Actions are validated (Read, Write, List, Tagging, Admin).
+Use `-expiry` for time-limited credentials (must be positive; 0 = no expiration).
+
 ### User lifecycle
 ```
 > s3.user.list
@@ -296,10 +306,13 @@ Secret Key: ...
 ### Backup and restore IAM state
 ```
 > s3.iam.export -file iam-backup.json
-> s3.iam.import -file iam-backup.json
+> s3.iam.import -file iam-backup.json -force
 > s3.config.show
 ```
 
+`s3.iam.export -file` writes with mode 0600 to protect credentials.
+`s3.iam.import` requires `-force` since it overwrites the entire IAM configuration.
+
 # One more trick
 You can skip the "fs." prefix, for all "fs.*" commands:
 ```