diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bbdc73c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# ~/bin — Custom CLI Utilities
+
+## Environment Variables
+
+All scripts accept environment variables as the primary credential source. If set, the secret store (macOS Keychain / Linux libsecret) is skipped.
+
+| Variable | Used by | Description |
+|---|---|---|
+| `GLM_API_KEY` | `claude-glm`, `glm-quota` | Zhipu AI (GLM) API key |
+| `TK_AI_API_TOKEN` | `claude-tk`, `ask` | TK AI API token |
+
+### Precedence
+
+1. **Environment variable** (if set, used directly)
+2. **Secret store** (macOS Keychain via `security`, or Linux `secret-tool`)
+3. **Error** if neither source provides a value
+
+### Usage Examples
+
+```sh
+# Override for a single invocation
+GLM_API_KEY=xxx claude-glm
+
+# Export for the session
+export TK_AI_API_TOKEN=xxx
+ask "how to find large files"
+```
+
+### Secret Store Setup
+
+**macOS (Keychain):**
+```sh
+security add-generic-password -a "$USER" -s GLM_API_KEY -w "YOUR_KEY"
+security add-generic-password -a "$USER" -s TK_AI_API_TOKEN -w "YOUR_KEY"
+```
+
+**Linux / Arch (libsecret):**
+```sh
+echo "YOUR_KEY" | secret-tool store --label "GLM API Key" service GLM_API_KEY
+echo "YOUR_KEY" | secret-tool store --label "AI API Token" service TK_AI_API_TOKEN
+```
diff --git a/ask b/ask
index e1278da..b38706f 100755
--- a/ask
+++ b/ask
@@ -48,14 +48,18 @@ while [[ "$1" == -* ]]; do
 done
 
 # ===== LOAD TOKEN =====
-case "$OS" in
-  macos)
-    API_TOKEN=$(security find-generic-password -a "$USER" -s "$KEY_NAME" -w 2>/dev/null | tr -d '\n')
-    ;;
-  *)
-    API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
-    ;;
-esac
+if [ -n "${!KEY_NAME}" ]; then
+  API_TOKEN="${!KEY_NAME}"
+else
+  case "$OS" in
+    macos)
+      API_TOKEN=$(security find-generic-password -a "$USER" -s "$KEY_NAME" -w 2>/dev/null | tr -d '\n')
+      ;;
+    *)
+      API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
+      ;;
+  esac
+fi
 
 if [ -z "$API_TOKEN" ]; then
   echo "❌ API token not found ($KEY_NAME)" >&2
diff --git a/claude-glm b/claude-glm
index 8b111ca..c2a9c76 100755
--- a/claude-glm
+++ b/claude-glm
@@ -13,6 +13,10 @@
 
 KEY_NAME="GLM_API_KEY"
 
+if [ -n "${!KEY_NAME}" ]; then
+  TOKEN="${!KEY_NAME}"
+fi
+
 get_token() {
   if command -v security >/dev/null 2>&1; then
     security find-generic-password -s "$KEY_NAME" -w 2>/dev/null && return
@@ -23,7 +27,9 @@ get_token() {
   return 1
 }
 
-TOKEN=$(get_token)
+if [ -z "$TOKEN" ]; then
+  TOKEN=$(get_token)
+fi
 
 if [ -z "$TOKEN" ]; then
   echo "❌ Missing GLM token ($KEY_NAME)"
diff --git a/claude-tk b/claude-tk
index cf2f9c8..6175de4 100755
--- a/claude-tk
+++ b/claude-tk
@@ -13,6 +13,10 @@
 
 KEY_NAME="TK_AI_API_TOKEN"
 
+if [ -n "${!KEY_NAME}" ]; then
+  TOKEN="${!KEY_NAME}"
+fi
+
 get_token() {
   if command -v security >/dev/null 2>&1; then
     security find-generic-password -s "$KEY_NAME" -w 2>/dev/null && return
@@ -23,7 +27,9 @@ get_token() {
   return 1
 }
 
-TOKEN=$(get_token)
+if [ -z "$TOKEN" ]; then
+  TOKEN=$(get_token)
+fi
 
 if [ -z "$TOKEN" ]; then
   echo "❌ Missing GPT token ($KEY_NAME)"
diff --git a/glm-quota b/glm-quota
index c7703ff..74d49de 100755
--- a/glm-quota
+++ b/glm-quota
@@ -43,17 +43,21 @@ while [[ $# -gt 0 ]]; do
 done
 
 # ===== LOAD TOKEN =====
-case "$OS" in
-  macos)
-    API_TOKEN=$(security find-generic-password -a "$USER" -s "$KEY_NAME" -w 2>/dev/null | tr -d '\n')
-    ;;
-  arch)
-    API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
-    ;;
-  *)
-    API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
-    ;;
-esac
+if [ -n "${!KEY_NAME}" ]; then
+  API_TOKEN="${!KEY_NAME}"
+else
+  case "$OS" in
+    macos)
+      API_TOKEN=$(security find-generic-password -a "$USER" -s "$KEY_NAME" -w 2>/dev/null | tr -d '\n')
+      ;;
+    arch)
+      API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
+      ;;
+    *)
+      API_TOKEN=$(secret-tool lookup service "$KEY_NAME" 2>/dev/null | tr -d '\n')
+      ;;
+  esac
+fi
 if [ -z "$API_TOKEN" ]; then
   echo -e "${RED}❌ API token not found ($KEY_NAME)${RESET}" >&2
   exit 1