@ardennguyen/zalo-agent-cli 2.1.0 → 2.1.1

package/.env.example

@@ -0,0 +1,30 @@
+# ============================================================================
+# zalo-agent-cli — Environment Configuration Template (.env.example)
+# ============================================================================
+# Recommended location: `~/.zalo-agent-cli/.env` (`<CONFIG_DIR>/.env`), or pass
+# `--env-file /path/to/.env` (`ZALO_ENV_FILE=/path/to/.env`).
+# Note: If you also use the `zalo-mcp` deployment wrapper, keep `zalo-mcp/.env`
+# for port settings (`ZALO_MCP_HTTP_PORT`, `ZALO_OA_WEBHOOK_PORT`) only, and put
+# all storage paths and engine settings in `<CONFIG_DIR>/.env` so `zalo-mcp` and
+# `zalo-agent` share a single source of truth.
+# CLI flags and shell environment variables take precedence over `.env` values.
+
+# ----------------------------------------------------------------------------
+# Storage Directories (Optional)
+# Uncomment to separate config, credentials, SQLite database, and media onto
+# different volumes or mounts in production:
+# ----------------------------------------------------------------------------
+# ZALO_CONFIG_DIR=
+# ZALO_CREDENTIALS_DIR=
+# ZALO_DATA_DIR=
+# ZALO_MEDIA_DIR=
+# ZALO_OA_DIR=
+
+# ----------------------------------------------------------------------------
+# Runtime & Protocol Options (Optional)
+# ----------------------------------------------------------------------------
+# Set to any value (e.g. 1) to disable the background npm update check:
+# ZALO_AGENT_NO_UPDATE_CHECK=1
+
+# Protocol version announced to Zalo (default: 691; set 685 to roll back):
+# ZALO_API_VERSION=691

package/README.md

@@ -138,7 +138,7 @@ Xem thêm: [Đa tài khoản & Proxy](https://github.com/ardennguyen/zalo-agent-
 - **Zalo Official Account (OA) API v3.0** — OAuth login, gửi tin nhắn, follower, tag, bài viết, cửa hàng, webhook listener, multi-OA
 - **MCP server** (stdio + HTTP) — 14 tools cho Claude Code và các MCP client: đọc, gửi (kể cả vào My Documents, đánh dấu Quan trọng/Khẩn cấp), thả cảm xúc, thu hồi tin, xem thành viên nhóm, liệt kê hội thoại gần đây và kiểm tra độ đầy đủ của cache
 - **Bộ nhớ đệm cục bộ (SQLite)** — `listen` ghi mọi tin nhắn vào `zalo.db`, `msg history` đọc từ cache, `sync` (hoặc `sync-mobile`) khôi phục toàn bộ lịch sử từ điện thoại vào `zalo.db` (giải mã transfer-sync-v2; xác nhận một lần trên điện thoại), mặc định lấy **toàn bộ** lịch sử (không còn mốc chặn 2024-01-01); thêm `--days <n>` hoặc `--from <YYYY-MM-DD>` nếu chỉ cần một khoảng. Dọn dẹp: `sync-media --prune <days|all>` giải phóng dung lượng nhưng giữ nguyên nội dung tin nhắn, `--prune-orphans` nhắm vào hội thoại tài khoản không còn, và `conv forget` xoá hẳn bản sao cục bộ của một hội thoại — không cái nào gửi gì tới Zalo. Luồng đồng bộ chỉ mang **liên kết** media chứ không mang file, nên sau khi lưu tin nhắn, `sync-mobile` **tự động tải media về** (thêm `--messages-only` nếu chỉ muốn tin nhắn); `sync-media` chạy lại/tiếp tục bước tải này, không cần xác nhận trên điện thoại. Ghi chú, tin ghim, bình chọn và nhắc hẹn nằm ngoài luồng tin nhắn — dùng `sync-boards`
-- Tự động tải media (ảnh/audio/video) — một downloader duy nhất cho `listen`, `msg history`, `mcp start` và các lệnh sync, lưu vào `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (MCP server có thể ghi đè bằng `media.downloadDir`)
+- Tự động tải media (ảnh/audio/video) — một downloader duy nhất cho `listen`, `msg history`, `mcp start` và các lệnh sync, lưu vào `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (hoặc tách riêng credentials, database `zalo.db`, media và OA sang các ổ đĩa/mount khác nhau qua `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / biến môi trường `ZALO_*_DIR` trong `~/.zalo-agent-cli/.env`; nếu dùng kèm `zalo-mcp`, chỉ nên giữ cấu hình PORT trong `zalo-mcp/.env` và đặt toàn bộ đường dẫn lưu trữ vào `<CONFIG_DIR>/.env`)
 - Thẻ chuyển khoản (55+ ngân hàng VN) & QR VietQR
 - Lắng nghe real-time với webhook & lưu JSONL local
 - `logout` hủy phiên **phía server** thật sự; `logout --purge` / `account remove` xóa sạch dữ liệu cục bộ
@@ -266,7 +266,7 @@ See also: [Multi-Account & Proxy](https://github.com/ardennguyen/zalo-agent-cli/
 - **Zalo Official Account (OA) API v3.0** — OAuth login, messaging, followers, tags, articles, store, webhook listener, multi-OA
 - **MCP server** (stdio + HTTP) — 14 tools for Claude Code and other MCP clients: read, send (to My Documents too, marked Important/Urgent), react, recall, list a group's members, list recent conversations, and check how complete the cache is
 - **Local SQLite cache** — `listen` writes every message to `zalo.db`, `msg history` reads from it, and `sync` (or `sync-mobile`) restores full history from the phone into `zalo.db` (transfer-sync-v2 decrypt; one confirmation on the phone), defaulting to **all** history (the old 2024-01-01 floor is gone), with `--days <n>` or `--from <YYYY-MM-DD>` to narrow it. Housekeeping: `sync-media --prune <days|all>` reclaims disk while keeping message text, `--prune-orphans` targets conversations the account no longer has, and `conv forget` removes a conversation's local copy entirely — none of which contact Zalo. The sync stream carries media **links**, not files, so a `sync-mobile` run **downloads its attachments automatically** once the messages are stored (`--messages-only` skips it); `sync-media` re-runs or resumes that fetch on its own, with no phone confirmation. Notes, pinned messages, polls and reminders live outside the message stream — `sync-boards` fetches those
-- Automatic media download — one downloader shared by `listen`, `msg history`, `mcp start` and the sync commands, saving to `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (the MCP server can override the root with `media.downloadDir`)
+- Automatic media download — one downloader shared by `listen`, `msg history`, `mcp start` and the sync commands, saving to `~/.zalo-agent-cli/accounts/<id>/media/<threadId>/` (or separate credentials, `zalo.db`, media, and OA credentials onto independent volumes/mounts via `--credentials-dir`, `--data-dir`, `--media-dir`, `--oa-dir` / `ZALO_*_DIR` in `~/.zalo-agent-cli/.env`; when using `zalo-mcp`, keep `zalo-mcp/.env` for PORT settings only and place all storage/engine settings in `<CONFIG_DIR>/.env`)
 - Bank cards (55+ VN banks) and VietQR payment images
 - Real-time listener with webhook forwarding and local JSONL archival
 - `logout` performs a real **server-side** session invalidation; `logout --purge` / `account remove` wipe all local data

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ardennguyen/zalo-agent-cli",
-    "version": "2.1.0",
+    "version": "2.1.1",
     "description": "CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments, Official Account API v3.0",
     "type": "module",
     "bin": {
@@ -8,6 +8,7 @@
     },
     "main": "./src/index.js",
     "files": [
+        ".env.example",
         "DISCLAIMER.md",
         "LICENSE",
         "NOTICE",
@@ -62,7 +63,6 @@
         "google-protobuf": "^3.21.4",
         "https-proxy-agent": "^9.1.0",
         "image-size": "^2.0.4",
-        "node-fetch": "^3.3.2",
         "undici": "^8.5.0",
         "zca-js": "2.2.0",
         "zod": "^4.4.3"
@@ -77,6 +77,6 @@
     },
     "allowScripts": {
         "better-sqlite3@13.0.3": true,
-        "@ardennguyen/zalo-agent-cli@2.0.1": true
+        "@ardennguyen/zalo-agent-cli@2.1.1": true
     }
 }

package/src/commands/conv.js

@@ -3,12 +3,11 @@
  * mute, unmute, read, unread, delete.
  */
 
-import { join } from "path";
 import { MuteAction } from "zca-js";
 import { getApi } from "../core/zalo-client.js";
 import { success, error, info, output, warning } from "../utils/output.js";
 import { getActive } from "../core/accounts.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDbPath } from "../core/credentials.js";
 import { initDb, getMessages, getReadStates, markThreadGone, getOrphanThreads, forgetThread } from "../core/db.js";
 import { recentConversations } from "../core/recent-conversations.js";
 import { describeReadState, readStateLabel } from "../core/read-state.js";
@@ -41,7 +40,7 @@ async function newestMessageAnchor(api, threadId, type) {
     try {
         const activeAcc = getActive();
         if (activeAcc) {
-            initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+            initDb(getAccountDbPath(activeAcc.ownId));
             cacheOpen = true;
         }
     } catch {
@@ -231,8 +230,7 @@ export function registerConvCommands(program, deps = {}) {
             }
 
             try {
-                const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
-                initDb(join(accountDir, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 // `-n` is documented as "max results per type", and the live
                 // path below honors that (up to `limit` friends AND up to
                 // `limit` groups). The cache path used to apply `limit`
@@ -524,7 +522,7 @@ export function registerConvCommands(program, deps = {}) {
 
             let result;
             try {
-                initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 const rows = getMessages(String(threadId), SEEN_ANCHOR_SCAN_DEPTH);
                 result = await markConversationRead(zaloApi(), { threadId, type, ownId: activeAcc.ownId, rows });
             } catch (e) {
@@ -749,8 +747,7 @@ export function registerConvCommands(program, deps = {}) {
                 error("Give a threadId, or --orphans to forget every conversation the account no longer has.");
                 process.exit(1);
             }
-            const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
-            initDb(join(accountDir, "zalo.db"));
+            initDb(getAccountDbPath(activeAcc.ownId));
 
             const targets = opts.orphans
                 ? getOrphanThreads().map((t) => ({ threadId: String(t.threadId), name: t.name, ...t }))

package/src/commands/listen.js

@@ -8,7 +8,7 @@ import { resolve, join } from "path";
 import { getApi, clearSession } from "../core/zalo-client.js";
 import { success, error, info, warning } from "../utils/output.js";
 import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDir } from "../core/credentials.js";
 import { acquireLock, releaseLock } from "../core/lock.js";
 import { createStageLock, startDaemonChannel } from "../core/daemon-channel.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
@@ -89,7 +89,7 @@ export function registerListenCommand(program) {
                 error(e.message);
                 process.exit(1);
             }
-            const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+            const accountDir = getAccountDir(activeAcc.ownId);
             if (!acquireLock(accountDir)) {
                 error(`Another listen daemon is already running for account ${activeAcc.ownId}.`);
                 process.exit(1);

package/src/commands/mcp.js

@@ -9,7 +9,7 @@ import { join } from "path";
 import { getApi, clearSession } from "../core/zalo-client.js";
 import { liveApi } from "../core/live-api.js";
 import { parseAccountId, selectDaemonAccount, loginDaemonAccount } from "../core/daemon-account.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDir, MEDIA_DIR } from "../core/credentials.js";
 import { acquireLock, releaseLock } from "../core/lock.js";
 import { createStageLock, startDaemonChannel } from "../core/daemon-channel.js";
 import { createSyncRunners } from "../core/daemon-sync.js";
@@ -148,7 +148,7 @@ export function registerMCPCommands(program) {
                 console.error("[mcp] Account selection failed:", e.message);
                 process.exit(1);
             }
-            const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+            const accountDir = getAccountDir(activeAcc.ownId);
 
             // This server now opens the account's WebSocket *and* writes to
             // zalo.db, which is exactly what the `listen` daemon does. Zalo
@@ -385,7 +385,7 @@ export function registerMCPCommands(program) {
                     threadId,
                     limit: 5,
                     concurrency: 2,
-                    mediaRoot: config.media?.downloadDir || undefined,
+                    mediaRoot: MEDIA_DIR || config.media?.downloadDir || undefined,
                 }).catch((e) => console.error(`[mcp] media download failed: ${e.message}`));
             }
 

package/src/commands/msg.js

@@ -11,7 +11,7 @@ import { withCurrentSenderNames } from "../core/current-user-names.js";
 import { success, error, info, output, warning } from "../utils/output.js";
 import { parseIntOption } from "../utils/parse-options.js";
 import { getActive } from "../core/accounts.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDir, getAccountDbPath } from "../core/credentials.js";
 import { initDb, getMessages, getMessageById, getDisplayName, getThreadType } from "../core/db.js";
 import { sendViaDaemon, getDaemonChannel, getSyncChannel, syncViaDaemon } from "../core/daemon-channel.js";
 import { fetchAndCacheHistory } from "../core/history-fetch.js";
@@ -47,7 +47,7 @@ function openAccountDb() {
     try {
         const acc = getActive();
         if (!acc) return false;
-        initDb(join(CONFIG_DIR, "accounts", acc.ownId, "zalo.db"));
+        initDb(getAccountDbPath(acc.ownId));
         return true;
     } catch {
         return false;
@@ -447,7 +447,7 @@ async function sendAttachments(api, absPaths, threadId, type, opts) {
     if (needsListener) {
         const acc = getActive();
         if (acc) {
-            const viaDaemon = await sendViaDaemon(join(CONFIG_DIR, "accounts", acc.ownId), {
+            const viaDaemon = await sendViaDaemon(getAccountDir(acc.ownId), {
                 paths: absPaths,
                 threadId,
                 type,
@@ -1211,7 +1211,7 @@ export function registerMsgCommands(program) {
 
             let row;
             try {
-                initDb(join(CONFIG_DIR, "accounts", activeAcc.ownId, "zalo.db"));
+                initDb(getAccountDbPath(activeAcc.ownId));
                 row = getMessageById(msgId);
             } catch (e) {
                 error(
@@ -1530,7 +1530,7 @@ export function registerMsgCommands(program) {
             let dbActive = false;
 
             try {
-                const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+                const accountDir = getAccountDir(activeAcc.ownId);
                 initDb(join(accountDir, "zalo.db"));
                 dbActive = true;
 
@@ -1625,7 +1625,7 @@ export function registerMsgCommands(program) {
                 // session the scan needs and is the one db writer (AGENTS.md
                 // §13). With a daemon up that is the daemon, and this command
                 // only displays what it returns.
-                const daemonDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+                const daemonDir = getAccountDir(activeAcc.ownId);
                 const daemon = getDaemonChannel(daemonDir);
                 let fetched = null;
                 let handledByDaemon = false;

package/src/commands/sync.js

@@ -1,7 +1,7 @@
 import { join } from "path";
 import { getApi } from "../core/zalo-client.js";
 import { getActive } from "../core/accounts.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDir } from "../core/credentials.js";
 import { acquireLock, releaseLock, checkLock } from "../core/lock.js";
 import { error, info, success, warning, output } from "../utils/output.js";
 import { parseIntAtLeast, parseIntOption } from "../utils/parse-options.js";
@@ -344,7 +344,7 @@ const MB = 1024 * 1024;
 
 /** Download attachments recorded by an earlier sync. No phone, no socket. */
 async function runMediaDownload(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     let kinds;
@@ -464,7 +464,7 @@ async function runMediaDownload(activeAcc, opts) {
 
 /** Reclaim media held by conversations the account no longer has. */
 async function runPruneOrphans(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     // The recorded definition: the same set `sync`'s warning counts and
@@ -521,7 +521,7 @@ async function runPruneOrphans(activeAcc, opts) {
 
 /** Delete downloaded media older than N days. Never removes message rows. */
 async function runMediaPrune(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     // "all" is a mode, not a very large number of days: a cutoff computed from
@@ -570,7 +570,7 @@ async function runMediaPrune(activeAcc, opts) {
 
 /** Sync board items + reminders for the cached threads. No phone, no socket. */
 async function runBoardSync(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     let api;
@@ -664,7 +664,7 @@ async function boardPass(api, opts) {
  * @param {{wait?: number, pages?: number, applyRemovals?: boolean}} opts
  */
 async function runReactionSync(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     let api;
@@ -862,7 +862,7 @@ function reportReactionDrain(stats, opts) {
 
 /** Walk the zCloud index. No phone, no socket. */
 async function runCloudSync(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     let api;
@@ -998,7 +998,7 @@ async function reconnectListener(api, waitMs = 30000) {
  * @param {{force?: boolean, wait?: number, days?: number}} opts
  */
 async function runTransferSync(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
 
     let api;
     let syncManager;
@@ -1501,7 +1501,7 @@ function printPlan(plan, win, jsonMode) {
  * @param {boolean} jsonMode
  */
 async function runUnifiedSync(activeAcc, opts, jsonMode) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
     initDb(join(accountDir, "zalo.db"));
 
     let api;
@@ -1890,7 +1890,7 @@ async function runUnifiedSync(activeAcc, opts, jsonMode) {
  * @param {{wait?: number}} opts
  */
 async function runSocketBackfill(activeAcc, opts) {
-    const accountDir = join(CONFIG_DIR, "accounts", activeAcc.ownId);
+    const accountDir = getAccountDir(activeAcc.ownId);
 
     // Build the SyncManager first so we can consult the local sync-freshness
     // marker BEFORE touching the network. A redundant run should neither open

package/src/core/accounts.js

@@ -5,19 +5,22 @@
 
 import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, rmSync } from "fs";
 import { join } from "path";
-import { CONFIG_DIR, deleteCredentials } from "./credentials.js";
+import { CONFIG_DIR, getAccountDir, deleteCredentials } from "./credentials.js";
 import { checkLock } from "./lock.js";
 
-const ACCOUNTS_FILE = `${CONFIG_DIR}/accounts.json`;
+function accountsFile() {
+    return join(CONFIG_DIR, "accounts.json");
+}
 
 function ensureDir() {
     mkdirSync(CONFIG_DIR, { recursive: true });
 }
 
 function load() {
-    if (!existsSync(ACCOUNTS_FILE)) return [];
+    const file = accountsFile();
+    if (!existsSync(file)) return [];
     try {
-        return JSON.parse(readFileSync(ACCOUNTS_FILE, "utf-8"));
+        return JSON.parse(readFileSync(file, "utf-8"));
     } catch {
         return [];
     }
@@ -25,8 +28,9 @@ function load() {
 
 function save(accounts) {
     ensureDir();
-    writeFileSync(ACCOUNTS_FILE, JSON.stringify(accounts, null, 2), "utf-8");
-    chmodSync(ACCOUNTS_FILE, 0o600);
+    const file = accountsFile();
+    writeFileSync(file, JSON.stringify(accounts, null, 2), "utf-8");
+    chmodSync(file, 0o600);
 }
 
 /** List all registered accounts. */
@@ -102,7 +106,7 @@ export function addAccount(ownId, name = "", proxy = null) {
  * @returns {{wiped: boolean, skippedLocked?: {pid: number}}}
  */
 export function wipeAccountDir(ownId) {
-    const accountDir = join(CONFIG_DIR, "accounts", ownId);
+    const accountDir = getAccountDir(ownId);
     if (!existsSync(accountDir)) return { wiped: false };
 
     const lockStatus = checkLock(accountDir);

package/src/core/credentials.js

@@ -1,14 +1,162 @@
 /**
- * Per-account credential storage at ~/.zalo-agent-cli/credentials/
+ * Per-account credential storage and configurable runtime storage paths.
+ *
+ * Defaults:
+ *   CONFIG_DIR      = ~/.zalo-agent-cli             (env: ZALO_CONFIG_DIR,      flag: --config-dir)
+ *   CREDENTIALS_DIR = <CONFIG_DIR>/credentials      (env: ZALO_CREDENTIALS_DIR, flag: --credentials-dir)
+ *   DATA_DIR        = <CONFIG_DIR>/accounts         (env: ZALO_DATA_DIR,        flag: --data-dir)
+ *   MEDIA_DIR       = null (<DATA_DIR>/<id>/media)  (env: ZALO_MEDIA_DIR,       flag: --media-dir)
+ *
  * All credential files use 0600 permissions (owner read/write only).
  */
 
 import { readFileSync, writeFileSync, unlinkSync, existsSync, mkdirSync, chmodSync } from "fs";
-import { join } from "path";
+import { join, resolve } from "path";
 import { homedir } from "os";
+import { parseEnv } from "node:util";
 
-export const CONFIG_DIR = join(homedir(), ".zalo-agent-cli");
-export const CREDENTIALS_DIR = join(CONFIG_DIR, "credentials");
+const defaultConfigDir = join(homedir(), ".zalo-agent-cli");
+
+/**
+ * Load environment variables from `.env` files without overwriting existing `process.env` keys.
+ * Search order (first defined value wins):
+ *   1. Explicit `envFile` (`--env-file <path>` or `ZALO_ENV_FILE`)
+ *   2. `<cwd>/.env` (skipped when `ZALO_SANDBOX_ACTIVE=1` so offline tests stay isolated)
+ *   3. `<configDir>/.env` (default `~/.zalo-agent-cli/.env`)
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.envFile]
+ * @param {string} [opts.configDir]
+ * @returns {string[]} Paths of `.env` files that were loaded
+ */
+export function loadDotEnvFiles(opts = {}) {
+    const candidates = [];
+    const explicit = opts.envFile || process.env.ZALO_ENV_FILE;
+    if (explicit) candidates.push(resolve(explicit));
+    if (process.env.ZALO_SANDBOX_ACTIVE !== "1") {
+        candidates.push(resolve(process.cwd(), ".env"));
+    }
+    const cfgRoot = opts.configDir
+        ? resolve(opts.configDir)
+        : process.env.ZALO_CONFIG_DIR
+          ? resolve(process.env.ZALO_CONFIG_DIR)
+          : defaultConfigDir;
+    candidates.push(join(cfgRoot, ".env"));
+
+    const loaded = [];
+    const seen = new Set();
+    for (const filePath of candidates) {
+        if (seen.has(filePath)) continue;
+        seen.add(filePath);
+        if (!existsSync(filePath)) continue;
+        try {
+            const parsed = parseEnv(readFileSync(filePath, "utf-8"));
+            for (const [k, v] of Object.entries(parsed)) {
+                if (process.env[k] === undefined) {
+                    process.env[k] = v;
+                }
+            }
+            loaded.push(filePath);
+        } catch {
+            /* ignore unreadable .env file */
+        }
+    }
+    return loaded;
+}
+
+export let CONFIG_DIR = process.env.ZALO_CONFIG_DIR ? resolve(process.env.ZALO_CONFIG_DIR) : defaultConfigDir;
+export let CREDENTIALS_DIR = process.env.ZALO_CREDENTIALS_DIR
+    ? resolve(process.env.ZALO_CREDENTIALS_DIR)
+    : join(CONFIG_DIR, "credentials");
+export let DATA_DIR =
+    process.env.ZALO_DATA_DIR || process.env.ZALO_DB_DIR
+        ? resolve(process.env.ZALO_DATA_DIR || process.env.ZALO_DB_DIR)
+        : join(CONFIG_DIR, "accounts");
+export let MEDIA_DIR = process.env.ZALO_MEDIA_DIR ? resolve(process.env.ZALO_MEDIA_DIR) : null;
+
+/**
+ * Override storage directories from CLI options, `.env` files, or runtime config.
+ * Updates live ESM bindings (CONFIG_DIR, CREDENTIALS_DIR, DATA_DIR, MEDIA_DIR)
+ * and synchronizes process.env so child helpers see the same paths.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.envFile] - Optional explicit `.env` file path (`--env-file` / `ZALO_ENV_FILE`)
+ * @param {boolean} [opts.loadEnv=true] - Whether to load `.env` files before resolving paths
+ * @param {string} [opts.configDir] - Root config directory (accounts.json, mcp-config.json, qr.png)
+ * @param {string} [opts.credentialsDir] - Credentials directory (cred_<ownId>.json)
+ * @param {string} [opts.dataDir] - Per-account runtime/database root (<dataDir>/<ownId>/zalo.db)
+ * @param {string} [opts.mediaDir] - Downloaded media root (<mediaDir>/<threadId>/)
+ * @param {string} [opts.oaDir] - Official Account credentials directory (oa-credentials.json)
+ */
+export function configureStoragePaths(opts = {}) {
+    if (opts.loadEnv !== false) {
+        loadDotEnvFiles({ envFile: opts.envFile, configDir: opts.configDir });
+    }
+
+    const nextConfig = opts.configDir || process.env.ZALO_CONFIG_DIR;
+    if (nextConfig) {
+        CONFIG_DIR = resolve(nextConfig);
+        if (opts.configDir) process.env.ZALO_CONFIG_DIR = CONFIG_DIR;
+    }
+
+    const nextCreds = opts.credentialsDir || process.env.ZALO_CREDENTIALS_DIR;
+    if (nextCreds) {
+        CREDENTIALS_DIR = resolve(nextCreds);
+        if (opts.credentialsDir) process.env.ZALO_CREDENTIALS_DIR = CREDENTIALS_DIR;
+    } else if (nextConfig) {
+        CREDENTIALS_DIR = join(CONFIG_DIR, "credentials");
+    }
+
+    const nextData = opts.dataDir || process.env.ZALO_DATA_DIR || process.env.ZALO_DB_DIR;
+    if (nextData) {
+        DATA_DIR = resolve(nextData);
+        if (opts.dataDir) process.env.ZALO_DATA_DIR = DATA_DIR;
+    } else if (nextConfig) {
+        DATA_DIR = join(CONFIG_DIR, "accounts");
+    }
+
+    if (opts.mediaDir !== undefined) {
+        MEDIA_DIR = opts.mediaDir ? resolve(opts.mediaDir) : null;
+        if (MEDIA_DIR) process.env.ZALO_MEDIA_DIR = MEDIA_DIR;
+        else delete process.env.ZALO_MEDIA_DIR;
+    } else if (process.env.ZALO_MEDIA_DIR) {
+        MEDIA_DIR = resolve(process.env.ZALO_MEDIA_DIR);
+    }
+
+    if (opts.oaDir) {
+        process.env.ZALO_OA_DIR = resolve(opts.oaDir);
+    }
+}
+
+/**
+ * Get the per-account runtime/database directory (<DATA_DIR>/<ownId>).
+ * @param {string} ownId
+ * @returns {string}
+ */
+export function getAccountDir(ownId) {
+    return join(DATA_DIR, String(ownId));
+}
+
+/**
+ * Get the per-account SQLite database path (<DATA_DIR>/<ownId>/zalo.db).
+ * @param {string} ownId
+ * @returns {string}
+ */
+export function getAccountDbPath(ownId) {
+    return join(getAccountDir(ownId), "zalo.db");
+}
+
+/**
+ * Resolve the media root directory for an account.
+ * Precedence: explicit override -> MEDIA_DIR (--media-dir / ZALO_MEDIA_DIR) -> <accountDir>/media.
+ * @param {string} accountDir
+ * @param {string|null} [overrideRoot]
+ * @returns {string}
+ */
+export function resolveMediaRoot(accountDir, overrideRoot = null) {
+    const custom = overrideRoot || MEDIA_DIR;
+    return custom ? resolve(custom) : resolve(accountDir, "media");
+}
 
 /** Ensure config directories exist. */
 function ensureDirs() {

package/src/core/logout.js

@@ -21,7 +21,7 @@
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { existsSync, rmSync } from "node:fs";
-import { CONFIG_DIR, deleteCredentials } from "./credentials.js";
+import { getAccountDir, deleteCredentials } from "./credentials.js";
 import { checkLock } from "./lock.js";
 
 const require = createRequire(import.meta.url);
@@ -164,7 +164,7 @@ const EMPTY_REPLY = /Failed to parse response data/;
  * @returns {{dbDeleted: boolean, mediaDeleted: boolean}}
  */
 export function deleteLocalHistory(ownId) {
-    const accountDir = join(CONFIG_DIR, "accounts", ownId);
+    const accountDir = getAccountDir(ownId);
     let dbDeleted = false;
     let mediaDeleted = false;
     if (existsSync(accountDir)) {
@@ -194,7 +194,7 @@ export function deleteLocalHistory(ownId) {
  * @returns {number|null}
  */
 export function lockHolder(ownId) {
-    const lock = checkLock(join(CONFIG_DIR, "accounts", ownId));
+    const lock = checkLock(getAccountDir(ownId));
     return lock.locked ? lock.pid : null;
 }
 

package/src/core/oa-client.js

@@ -1,22 +1,32 @@
 /**
  * Zalo Official Account API v3.0 client.
- * Wraps OA REST endpoints with node-fetch. No dependency on zca-js.
+ * Wraps OA REST endpoints with native fetch. No dependency on zca-js.
  * Credentials stored in ~/.zalo-agent/oa-credentials.json.
  */
 
 import fs from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { homedir } from "node:os";
-import nodefetch from "node-fetch";
 
 const V3_BASE = "https://openapi.zalo.me/v3.0/oa";
 const V2_BASE = "https://openapi.zalo.me/v2.0/oa";
-const DATA_DIR = join(homedir(), ".zalo-agent");
-const OA_CREDS_FILE = join(DATA_DIR, "oa-credentials.json");
+
+/**
+ * Resolve the Official Account data directory (defaults to ~/.zalo-agent, or ZALO_OA_DIR).
+ * @returns {string}
+ */
+export function getOADataDir() {
+    return process.env.ZALO_OA_DIR ? resolve(process.env.ZALO_OA_DIR) : join(homedir(), ".zalo-agent");
+}
+
+function getOACredsFile() {
+    return join(getOADataDir(), "oa-credentials.json");
+}
 
 /** Ensure data directory exists. */
 function ensureDir() {
-    if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+    const dir = getOADataDir();
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
 const OAUTH_URL = "https://oauth.zaloapp.com/v4/oa/permission";
@@ -25,12 +35,13 @@ const TOKEN_URL = "https://oauth.zaloapp.com/v4/oa/access_token";
 /** Save full OA credentials to disk with restricted file permissions. */
 export function saveOACreds(data, oaId = "default") {
     ensureDir();
+    const credsFile = getOACredsFile();
     let creds = {};
-    if (fs.existsSync(OA_CREDS_FILE)) {
-        creds = JSON.parse(fs.readFileSync(OA_CREDS_FILE, "utf8"));
+    if (fs.existsSync(credsFile)) {
+        creds = JSON.parse(fs.readFileSync(credsFile, "utf8"));
     }
     creds[oaId] = { ...creds[oaId], ...data, updatedAt: new Date().toISOString() };
-    fs.writeFileSync(OA_CREDS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    fs.writeFileSync(credsFile, JSON.stringify(creds, null, 2), { mode: 0o600 });
 }
 
 /** Save OA access token to disk (backward compat). */
@@ -40,8 +51,9 @@ export function saveOAToken(accessToken, oaId = "default") {
 
 /** Load full OA credentials from disk. */
 export function loadOACreds(oaId = "default") {
-    if (!fs.existsSync(OA_CREDS_FILE)) return null;
-    const creds = JSON.parse(fs.readFileSync(OA_CREDS_FILE, "utf8"));
+    const credsFile = getOACredsFile();
+    if (!fs.existsSync(credsFile)) return null;
+    const creds = JSON.parse(fs.readFileSync(credsFile, "utf8"));
     return creds[oaId] || null;
 }
 
@@ -70,7 +82,7 @@ export function getOAuthUrl(appId, redirectUri = "http://localhost:3456/callback
 
 /** Exchange authorization code for access + refresh tokens. */
 export async function exchangeCode(code, appId, secretKey, redirectUri = "http://localhost:3456/callback") {
-    const res = await nodefetch(TOKEN_URL, {
+    const res = await fetch(TOKEN_URL, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded", secret_key: secretKey },
         body: new URLSearchParams({
@@ -85,7 +97,7 @@ export async function exchangeCode(code, appId, secretKey, redirectUri = "http:/
 
 /** Refresh access token using refresh token. */
 export async function refreshAccessToken(refreshToken, appId, secretKey) {
-    const res = await nodefetch(TOKEN_URL, {
+    const res = await fetch(TOKEN_URL, {
         method: "POST",
         headers: { "Content-Type": "application/x-www-form-urlencoded", secret_key: secretKey },
         body: new URLSearchParams({
@@ -106,7 +118,7 @@ async function oaFetch(url, { method = "GET", body, token, isFormData = false }
     if (body && !isFormData) opts.body = JSON.stringify(body);
     if (body && isFormData) opts.body = body;
 
-    const res = await nodefetch(url, opts);
+    const res = await fetch(url, opts);
     const data = await res.json();
     if (data.error && data.error !== 0) {
         throw new Error(`OA API error ${data.error}: ${data.message || JSON.stringify(data)}`);
@@ -281,7 +293,7 @@ export async function removeFollowerFromTag(userId, tagName, oaId = "default") {
 /** Upload image to OA (returns attachment_id). */
 export async function uploadImage(filePath, oaId = "default") {
     const token = getToken(oaId);
-    // Use native FormData-like via node-fetch's Blob
+    // Use native Blob and FormData
     const fileData = fs.readFileSync(filePath);
     const blob = new (await import("node:buffer")).Blob([fileData]);
     const form = new globalThis.FormData();

package/src/core/sync-v2/index.js

@@ -419,12 +419,15 @@ export class SyncV2 {
     constructor(api, accountName) {
         this.api = api;
         this.accountName = accountName;
-        this.accountDir = resolve(
-            process.env.USERPROFILE || process.env.HOME || "",
-            ".zalo-agent-cli",
-            "accounts",
-            accountName,
-        );
+        const dataRoot =
+            process.env.ZALO_DATA_DIR ||
+            process.env.ZALO_DB_DIR ||
+            resolve(
+                process.env.ZALO_CONFIG_DIR ||
+                    resolve(process.env.USERPROFILE || process.env.HOME || "", ".zalo-agent-cli"),
+                "accounts",
+            );
+        this.accountDir = resolve(dataRoot, accountName);
     }
 
     /** Build opaque-globalId -> {id, name, type} from the friend + group lists. */

package/src/core/sync-v2/media.js

@@ -482,9 +482,10 @@ export async function downloadSyncedMedia(opts = {}) {
         }
     }
 
-    // The MCP server honours a configured download dir; everything else files
-    // media under the account's own data dir.
-    const mediaRoot = mediaRootOpt ? resolve(mediaRootOpt) : resolve(accountDir, "media");
+    // Explicit mediaRootOpt or global ZALO_MEDIA_DIR (--media-dir) overrides the
+    // per-account default (<accountDir>/media).
+    const configuredRoot = mediaRootOpt || process.env.ZALO_MEDIA_DIR;
+    const mediaRoot = configuredRoot ? resolve(configuredRoot) : resolve(accountDir, "media");
 
     // Folders are ids, so without this the media tree is unreadable by a human.
     // Written before any download, so an interrupted run still leaves an index.

package/src/core/sync.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import { resolve } from "path";
 import crypto from "crypto";
-import { CONFIG_DIR } from "./credentials.js";
+import { getAccountDir } from "./credentials.js";
 import {
     initDb,
     insertMessage,
@@ -19,7 +19,7 @@ const THREAD_TYPE_USER = 0;
 const THREAD_TYPE_GROUP = 1;
 
 function resolveAccountDir(accountName) {
-    return resolve(CONFIG_DIR, "accounts", accountName);
+    return resolve(getAccountDir(accountName));
 }
 
 /** Zalo Web's own client only ever seems to backfill about this far on a

package/src/index.js

@@ -31,6 +31,7 @@ import { registerMCPCommands } from "./commands/mcp.js";
 import { registerSyncCommands } from "./commands/sync.js";
 import { autoLogin } from "./core/zalo-client.js";
 import { getActive } from "./core/accounts.js";
+import { configureStoragePaths } from "./core/credentials.js";
 import { logoutNeedsSession } from "./core/logout.js";
 import { checkForUpdates, selfUpdate } from "./utils/update-check.js";
 import { applyCachedThreadType } from "./utils/thread-type.js";
@@ -46,10 +47,31 @@ program
     .description("CLI tool for Zalo automation — multi-account, proxy, bank transfers, QR payments")
     .version(pkg.version)
     .option("--json", "Output results as JSON (machine-readable)")
+    .option("--env-file <path>", "Load environment variables from a .env file (env: ZALO_ENV_FILE)")
+    .option("--config-dir <dir>", "Config directory (default: ~/.zalo-agent-cli, env: ZALO_CONFIG_DIR)")
+    .option(
+        "--credentials-dir <dir>",
+        "Credentials directory (default: <config-dir>/credentials, env: ZALO_CREDENTIALS_DIR)",
+    )
+    .option(
+        "--data-dir <dir>",
+        "Per-account database and runtime directory (default: <config-dir>/accounts, env: ZALO_DATA_DIR)",
+    )
+    .option("--media-dir <dir>", "Downloaded media directory (default: <data-dir>/<ownId>/media, env: ZALO_MEDIA_DIR)")
+    .option("--oa-dir <dir>", "Official Account credentials directory (default: ~/.zalo-agent, env: ZALO_OA_DIR)")
     .hook("preAction", async (thisCommand, actionCommand) => {
+        const globalOpts = program.opts();
+        configureStoragePaths({
+            envFile: globalOpts.envFile,
+            configDir: globalOpts.configDir,
+            credentialsDir: globalOpts.credentialsDir,
+            dataDir: globalOpts.dataDir,
+            mediaDir: globalOpts.mediaDir,
+            oaDir: globalOpts.oaDir,
+        });
         const cmdName = thisCommand.args?.[0] || thisCommand.name();
         // Suppress zca-js internal logs in JSON mode to keep stdout clean for piping
-        if (program.opts().json || cmdName === "mcp") {
+        if (globalOpts.json || cmdName === "mcp") {
             // Suppress zca-js stdout logs: JSON mode needs clean output, MCP uses stdout as transport
             process.env.ZALO_JSON_MODE = "1";
         } else if (cmdName !== "oa") {

package/src/mcp/mcp-config.js

@@ -6,7 +6,9 @@ import { readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { CONFIG_DIR } from "../core/credentials.js";
 
-const MCP_CONFIG_FILE = join(CONFIG_DIR, "mcp-config.json");
+function mcpConfigFile() {
+    return join(CONFIG_DIR, "mcp-config.json");
+}
 
 /** Default MCP config — sensible defaults for local development */
 export function getDefaultConfig() {
@@ -47,7 +49,7 @@ export function getDefaultConfig() {
 export function loadMCPConfig(configPath) {
     const defaults = getDefaultConfig();
     try {
-        const raw = readFileSync(configPath || MCP_CONFIG_FILE, "utf-8");
+        const raw = readFileSync(configPath || mcpConfigFile(), "utf-8");
         const saved = JSON.parse(raw);
         // Shallow merge: saved values override defaults
         return {
@@ -77,7 +79,7 @@ export function loadMCPConfig(configPath) {
  * @returns {{config: object, problem: string|null}}
  */
 export function readMCPConfig(configPath) {
-    const file = configPath || MCP_CONFIG_FILE;
+    const file = configPath || mcpConfigFile();
     let raw;
     try {
         raw = readFileSync(file, "utf-8");
@@ -99,7 +101,7 @@ export function readMCPConfig(configPath) {
  */
 export function saveMCPConfig(config) {
     mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(MCP_CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+    writeFileSync(mcpConfigFile(), JSON.stringify(config, null, 2), "utf-8");
 }
 
 /**

package/src/mcp/mcp-tools.js

@@ -824,7 +824,7 @@ export function registerTools(server, api, buffer, filter, config, nameCache, ac
                         threadId: String(row?.threadId || buffered?.threadId || threadId || ""),
                         limit: 50,
                         concurrency: 2,
-                        mediaRoot: mediaConfig.downloadDir || undefined,
+                        mediaRoot: process.env.ZALO_MEDIA_DIR || mediaConfig.downloadDir || undefined,
                     });
                     localPath = getMessageById(messageId)?.localPath || null;
                     if (!localPath) {

package/src/utils/qr-display.js

@@ -19,8 +19,6 @@ import { platform } from "os";
 import { CONFIG_DIR } from "../core/credentials.js";
 import { info } from "./output.js";
 
-const QR_PATH = resolve(CONFIG_DIR, "qr.png");
-
 /** Get platform-specific command to open a file. */
 function getOpenCommand() {
     switch (platform()) {
@@ -42,18 +40,19 @@ function getOpenCommand() {
 export function displayQR(event) {
     const imageB64 = event.data?.image || "";
     const jsonMode = process.env.ZALO_JSON_MODE === "1";
+    const qrPath = getQRPath();
 
     // Always save PNG to config dir (needed by HTTP server and agents)
     if (imageB64) {
         try {
             mkdirSync(CONFIG_DIR, { recursive: true });
-            writeFileSync(QR_PATH, Buffer.from(imageB64, "base64"));
+            writeFileSync(qrPath, Buffer.from(imageB64, "base64"));
         } catch {}
     }
 
     // Also fire-and-forget the zca-js built-in save
     if (event.actions?.saveToFile) {
-        event.actions.saveToFile(QR_PATH).catch(() => {});
+        event.actions.saveToFile(qrPath).catch(() => {});
     }
 
     // JSON mode: structured output for AI agents — no terminal escapes, no noise
@@ -63,7 +62,7 @@ export function displayQR(event) {
                 JSON.stringify({
                     event: "qr",
                     image: imageB64,
-                    file: QR_PATH,
+                    file: qrPath,
                     dataUrl: `data:image/png;base64,${imageB64}`,
                 }),
             );
@@ -78,8 +77,8 @@ export function displayQR(event) {
         process.stdout.write(`\x1b]1337;File=inline=1;width=30;preserveAspectRatio=1:${b64ForTerm}\x07\n`);
 
         const openCmd = getOpenCommand();
-        info(`QR image saved: ${QR_PATH}`);
-        info(`To open: ${openCmd} "${QR_PATH}"`);
+        info(`QR image saved: ${qrPath}`);
+        info(`To open: ${openCmd} "${qrPath}"`);
         info("Copy this URL and paste in any browser to view QR:");
         console.log(`data:image/png;base64,${imageB64}`);
     }
@@ -87,5 +86,5 @@ export function displayQR(event) {
 
 /** Get the QR image path. */
 export function getQRPath() {
-    return QR_PATH;
+    return resolve(CONFIG_DIR, "qr.png");
 }

package/src/utils/qr-http-server.js

@@ -6,7 +6,6 @@
 
 import http from "http";
 import { readFileSync, existsSync, statSync } from "fs";
-import nodefetch from "node-fetch";
 import { info } from "./output.js";
 
 /**
@@ -180,7 +179,7 @@ setInterval(async()=>{
 
         // Auto-detect public IP for VPS users
         try {
-            const res = await nodefetch("https://api.ipify.org", { timeout: 3000 });
+            const res = await fetch("https://api.ipify.org", { signal: AbortSignal.timeout(3000) });
             publicIp = (await res.text()).trim() || null;
         } catch {}
 

package/src/utils/thread-type.js

@@ -20,9 +20,8 @@
  * `upsertThread` refuses to downgrade a group regardless, so this is the
  * ergonomic half of the fix, not the safety half.
  */
-import { join } from "node:path";
 import { getActive } from "../core/accounts.js";
-import { CONFIG_DIR } from "../core/credentials.js";
+import { getAccountDbPath } from "../core/credentials.js";
 import { initDb, getThreadType } from "../core/db.js";
 
 /**
@@ -34,7 +33,7 @@ import { initDb, getThreadType } from "../core/db.js";
 function lookupCachedType(threadId) {
     const acc = getActive();
     if (!acc) return null;
-    initDb(join(CONFIG_DIR, "accounts", acc.ownId, "zalo.db"));
+    initDb(getAccountDbPath(acc.ownId));
     return getThreadType(threadId);
 }