Documentation
Complete command reference for the openzca CLI. Both openzca and zca work as the command name.
Installation
Requires Node.js 18+. Works on macOS, Linux, and Windows.
npm (recommended)
$ npm i -g openzca@latest
macOS / Linux
$ curl -fsSL https://openzca.com/install.sh | bash
Windows (PowerShell)
PS> irm https://openzca.com/install.ps1 | iex
Run without installing
$ npx openzca --help
Quick Start
Terminal
# Login with QR code
$ openzca auth login
# Send a message
$ openzca msg send 123456 "Hello from CLI!"
# Send a formatted message to a group
$ openzca msg send GID "**bold** and *italic* with @Alice" -g
# Listen for incoming messages
$ openzca listen --webhook http://localhost:3000/hook
# Enable local database and sync
$ openzca db enable
$ openzca db sync
Global Options
These options can be used with any command.
-p, --profile <name>
Select a named profile for this command
--debug
Enable debug logging
--debug-file <path>
Debug log file path
-V, --version
Output the version number
account — Multi-account profile management
Manage multiple Zalo accounts with named profiles. Each profile stores its own credentials, cache, and database.
| Command | Description |
|---|---|
account list ls, l | List all account profiles |
account current whoami | Show current active profile |
account switch <name> use | Set default profile |
account add [name] new | Create a new profile (default: "default") |
account label <name> <label> | Set a display label for a profile |
account remove <name> rm | Remove a profile and its data |
Examples
# Create work and personal profiles
$ openzca account add work
$ openzca account add personal
# Switch to work profile
$ openzca account switch work
# Run a single command with a specific profile
$ openzca --profile personal msg send 123 "Hi"
auth — Authentication & cache
Login, logout, and manage the local friends/groups cache.
| Command | Description |
|---|---|
auth login | Login with QR code |
auth login-cred [file] login-creds | Login using a credential JSON file |
auth logout | Remove saved credentials from active profile |
auth status | Show login status |
auth cache-refresh | Refresh friends/groups cache from server |
auth cache-info | Show cache metadata (last updated, counts) |
auth cache-clear | Clear local cache |
auth login options
-q, --qr-path <path>
Save QR code image to file
--open-qr
Open QR image with system viewer
--qr-base64
Output QR as base64 data URL and return immediately (integration mode)
Inline QR rendering is supported in Ghostty, Kitty, WezTerm, and iTerm2 via the Kitty Graphics Protocol or iTerm2 inline images. Other terminals get an ASCII QR fallback.
msg — Messaging
Send text, media, files, reactions, and manage conversations. Use -g to target group threads.
| Command | Description |
|---|---|
msg send <threadId> <message> | Send text with formatting and @mentions |
msg image <threadId> [file] | Send image(s) from file or URL |
msg video <threadId> [file] | Send video(s); single .mp4 uses native video mode |
msg voice <threadId> [file] | Send voice message (.aac, .mp3, .m4a, .wav, .ogg) |
msg sticker <threadId> <stickerId> | Send a sticker |
msg link <threadId> <url> | Send a link preview |
msg card <threadId> <contactId> | Send a contact card |
msg react <msgId> <cliMsgId> <threadId> <reaction> | React to a message |
msg typing <threadId> | Send typing indicator |
msg forward <message> <targets...> | Forward text to multiple targets |
msg delete <msgId> <cliMsgId> <uidFrom> <threadId> | Delete a message |
msg undo <msgId> <cliMsgId> <threadId> | Recall your sent message |
msg edit <msgId> <cliMsgId> <threadId> <message> | Edit a message (undo + resend) |
msg upload <arg1> [arg2] | Upload and send file(s) |
msg recent <threadId> | List recent messages |
msg pin <threadId> | Pin a conversation |
msg unpin <threadId> | Unpin a conversation |
msg list-pins | List pinned conversations |
msg member-info <userId> | Get member/user profile info |
msg send options
-g, --group
Send to a group thread
--raw
Skip Markdown formatting and @mention resolution
--reply-id <id>
Quote-reply to a message by its stored ID from the local DB
--reply-message <json>
Quote-reply using a raw message.data object or listen --raw payload
msg image / video / voice / upload options
-u, --url <url>
Send from URL (repeatable for multiple files)
-m, --message <message>
Caption text (image and video only)
--thumbnail <pathOrUrl>
Custom video thumbnail (video only)
-g, --group
Send to a group thread
msg recent options
-n, --count <count>
Number of messages to fetch 20
--source <source>
Data source:
live, db, or auto live
-j, --json
Output as JSON
msg delete options
--only-me
Delete only for yourself
Reaction values: Use emoji directly or one of the named enums:
heart, like, haha, wow, cry, angry.
Examples
# Send formatted text to a group with @mention
$ openzca msg send GID "**Hello** @Alice, check this out!" -g
# Send image from URL with caption
$ openzca msg image 123456 -u https://example.com/photo.jpg -m "Look at this"
# Reply to a message from the local database
$ openzca msg send GID "I agree!" -g --reply-id abc123
# Upload a file to a group
$ openzca msg upload GID ./report.pdf -g
group — Group management
Create groups, manage members, handle invite links, run polls, and configure group settings.
| Command | Description |
|---|---|
group list | List all groups |
group info <groupId> | Get group details |
group members <groupId> | List group members |
group create <name> <members...> | Create a new group |
group rename <groupId> <name> | Rename a group |
group avatar <groupId> <file> | Change group avatar |
group settings <groupId> | Update group settings |
group add <groupId> <userIds...> | Add members to group |
group remove <groupId> <userIds...> | Remove members from group |
group add-deputy <groupId> <userId> | Promote member to deputy |
group remove-deputy <groupId> <userId> | Demote deputy |
group transfer <groupId> <newOwnerId> | Transfer group ownership |
group block <groupId> <userId> | Block a member |
group unblock <groupId> <userId> | Unblock a member |
group blocked <groupId> | List blocked members |
group enable-link <groupId> | Enable invite link |
group disable-link <groupId> | Disable invite link |
group link-detail <groupId> | Get invite link details |
group join-link <linkId> | Join a group via invite link |
group pending <groupId> | List pending join requests |
group review <groupId> <userId> <action> | Approve or deny join request |
group leave <groupId> | Leave a group |
group disperse <groupId> | Disperse (disband) a group |
group settings options
--lock-name / --unlock-name
Lock or unlock group name changes
--sign-admin / --no-sign-admin
Enable or disable admin signature
group poll
Create and manage polls within groups.
| Command | Description |
|---|---|
group poll create <groupId> | Create a poll |
group poll detail <pollId> | Get poll details and results |
group poll vote <pollId> | Vote on a poll |
group poll lock <pollId> | Close a poll |
group poll share <pollId> | Share a poll |
group poll create options
-q, --question <text>
Poll question required
-o, --option <text>
Poll option (repeatable, min 2) required
--multi
Allow multiple selections
--allow-add-option
Allow members to add options
--hide-vote-preview
Hide real-time vote counts
--anonymous
Anonymous voting
--expire-ms <ms>
Auto-close after N milliseconds
Examples
# Create a poll
$ openzca group poll create GID -q "Lunch spot?" -o "Pizza" -o "Sushi" -o "Pho" --multi
# Vote on a poll
$ openzca group poll vote POLL_ID -o 0 -o 2
friend — Friend management
Search users, manage friend requests, aliases, and blocking.
| Command | Description |
|---|---|
friend list | List all friends |
friend find <query> | Find user by phone, username, or name |
friend online | List online friends |
friend recommendations | Get friend recommendations |
friend add <userId> | Send friend request |
friend accept <userId> | Accept friend request |
friend reject <userId> | Reject friend request |
friend cancel <userId> | Cancel sent friend request |
friend sent | List sent friend requests |
friend request-status <userId> | Check friend request status |
friend remove <userId> | Remove a friend |
friend alias <userId> <alias> | Set display alias for a friend |
friend remove-alias <userId> | Remove alias |
friend aliases | List all aliases |
friend block <userId> | Block a user |
friend unblock <userId> | Unblock a user |
friend block-feed <userId> | Block user from viewing your feed |
friend unblock-feed <userId> | Unblock user from viewing your feed |
friend boards <conversationId> | Get boards in a conversation |
Notable options
-j, --json
Output as JSON (available on list, find, online, recommendations, sent, aliases, boards)
-m, --message <text>
Custom message for friend add "Hello!"
me — Profile & account
View and update your Zalo profile, manage avatars, and set online status.
| Command | Description |
|---|---|
me info | Get your account info |
me id | Get your user ID |
me update | Update profile fields |
me avatar <file> | Change profile avatar |
me avatars | List avatar history |
me delete-avatar <id> | Delete an avatar from history |
me reuse-avatar <id> | Reuse a previous avatar |
me status <online|offline> | Set online status |
me last-online <userId> | Check when a user was last online |
me update options
--name <name>
Set display name
--gender <gender>
Set gender (
male or female)
--birthday <date>
Set birthday (YYYY-MM-DD format)
db — Local SQLite database
Profile-scoped SQLite message persistence. Enable the database, sync data from the server, and query messages offline with time-range filters.
Default path:
~/.openzca/profiles/<profile>/messages.sqlite. Uses WAL mode for concurrent reads.
Database management
| Command | Description |
|---|---|
db enable | Enable local SQLite persistence |
db disable | Disable automatic DB persistence |
db reset | Delete the local SQLite DB file |
db status | Show DB status, message counts, and file path |
db enable options
--path <path>
Custom database file path
db reset options
-y, --yes
Skip confirmation prompt
--drop-config
Also remove the DB configuration
Stored data queries
| Command | Description |
|---|---|
db me info | Show stored self profile |
db me id | Show stored self user ID |
db group list | List groups in DB |
db group info <groupId> | Show stored group info |
db group members <groupId> | List stored group members |
db group messages <groupId> | List stored messages for a group |
db friend list | List friends in DB |
db friend find <query> | Find stored friends by ID or name |
db friend info <userId> | Show stored friend info |
db friend messages <userId> | List stored DM messages |
db chat list | List all chats in DB |
db chat info <chatId> | Show stored chat info |
db chat messages <chatId> | List stored chat messages |
db message get <id> | Read one stored message by msgId, cliMsgId, or uid |
Message query options
Available on db group messages, db friend messages, and db chat messages.
--since <duration>
Messages from the last N time units (e.g.
7d, 24h, 1d2h30m)
--from <time>
Start time (ISO 8601, unix seconds/ms, or parseable date string)
--until, --to <time>
End time (same formats as --from)
--limit <count>
Maximum number of messages 20
--all
Return all matching messages (no limit)
--oldest-first
Sort oldest first (default: newest first)
-j, --json
Output as JSON
Time filter formats: Relative durations (
7m, 24h, 1d, 2w, 1d2h30m), ISO timestamps (2026-03-21T10:00:00+07:00), Unix seconds or milliseconds, or any string parseable by Date.parse().
db sync
Sync data from the Zalo server into the local database.
| Command | Description |
|---|---|
db sync | Sync all (groups + friends + chats) |
db sync all | Explicit full sync (same as above) |
db sync groups | Sync group directory, members, and full history |
db sync friends | Sync friend directory only |
db sync chats | Sync discoverable DM/chat windows |
db sync group <groupId> | Sync one group with full history |
db sync chat <chatId> | Sync one chat |
db sync options
-n, --count <count>
Max messages to sync per chat 200
-j, --json
Output as JSON
Examples
# Enable and sync everything
$ openzca db enable
$ openzca db sync
# Query last 7 days of group messages
$ openzca db group messages GID --since 7d
# Export DM history as JSON
$ openzca db friend messages 123456 --all -j > chat.json
# Look up a specific message
$ openzca db message get MSG_ID -j
listen — Real-time message listener
WebSocket-powered listener for incoming messages with webhook forwarding, media caching, and supervised mode.
-e, --echo
Auto-reply with the received message
-p, --prefix <prefix>
Only process messages matching this prefix
-w, --webhook <url>
POST each message payload to a webhook URL
-r, --raw
Output raw JSON per line (for piping)
--db / --no-db
Force enable or disable DB writes for this session
-k, --keep-alive
Auto-reconnect on disconnect
--supervised
Supervisor mode with lifecycle JSON events (connected, heartbeat, error, closed)
--heartbeat-ms <ms>
Lifecycle heartbeat interval 30000
--recycle-ms <ms>
Force recycle listener after N ms (exits with code 75)
Raw output fields:
threadId, msgId, cliMsgId, content, type, timestamp, senderId, senderName, chatType, mentions, mediaPath, mediaUrl, quote, and more. See --raw output for full schema.
Examples
# Listen with webhook and auto-reconnect
$ openzca listen --webhook http://localhost:3000/hook -k
# Supervised mode for process managers
$ openzca listen --supervised --keep-alive --recycle-ms 1800000
# Pipe raw JSON to jq
$ openzca listen --raw | jq '.content'
# Only listen for messages starting with "!"
$ openzca listen --prefix "!" --webhook http://localhost:3000/bot
Text Formatting
When sending messages with msg send, openzca parses Markdown-style syntax into Zalo text styles. Use --raw to skip formatting.
| Syntax | Result |
|---|---|
| **bold** | Bold text |
| __bold__ | Bold text (alternative) |
| *italic* | Italic text |
| _italic_ | Italic text (alternative) |
| ***bold italic*** | Bold + italic |
| ~~strikethrough~~ | Strikethrough text |
| # Heading | Large bold heading (H1) |
| ## Heading | Bold heading (H2) |
| ### Heading | Heading (H3) |
| #### Heading | Heading (H4) |
| - item | Unordered list (also * and +) |
| 1. item | Ordered list |
| > quote | Blockquote (indented) |
| ```code``` | Fenced code block |
Color & size tags
Plain-text color and size tags for additional styling:
| Syntax | Result |
|---|---|
| {red}text{/red} | Red colored text |
| {orange}text{/orange} | Orange colored text |
| {yellow}text{/yellow} | Yellow colored text |
| {green}text{/green} | Green colored text |
| {big}text{/big} | Large text |
| {small}text{/small} | Small text |
| {underline}text{/underline} | Underlined text |
@Mentions in groups
When sending to a group (-g), @Name or @userId resolves against the group member list. Matching works against user IDs, display names, and Zalo names. Mentions work inside styled text (e.g., **@Alice**).
Ambiguous matches will fail. If multiple members match a partial name, the command will error. Use a more specific name or the full user ID.
Environment Variables
Override defaults with environment variables. All are optional.
| Variable | Default | Description |
|---|---|---|
| Profile & Data | ||
| OPENZCA_HOME | ~/.openzca | Override default data directory |
| OPENZCA_PROFILE | Select active profile (without --profile flag) | |
| ZCA_PROFILE | Legacy profile alias | |
| Debug | ||
| OPENZCA_DEBUG | 0 | Enable debug logging (1 to enable) |
| OPENZCA_DEBUG_FILE | ~/.openzca/logs/openzca-debug.log | Debug log file path |
| QR Code Rendering | ||
| OPENZCA_QR_OPEN | 0 | Auto-open QR image (1 to enable) |
| OPENZCA_QR_AUTO_OPEN | 1 (non-interactive) | Auto-open in headless mode (0 to disable) |
| OPENZCA_QR_RENDER | auto | Force QR mode: kitty, iterm, ascii, auto |
| OPENZCA_QR_ASCII | 1 | ASCII QR fallback (0 to disable) |
| OPENZCA_QR_DISABLE_ITERM_INLINE | 0 | Disable iTerm2 inline QR (1 to force ASCII) |
| OPENZCA_QR_WIDTH | 34 | iTerm2 QR width in cells (16-80) |
| Listener | ||
| OPENZCA_LISTEN_MEDIA_DIR | Explicit inbound media cache directory | |
| OPENZCA_LISTEN_MEDIA_MAX_BYTES | 20971520 | Max bytes per inbound media file (20 MB) |
| OPENZCA_LISTEN_MEDIA_MAX_FILES | 4 | Max inbound media files per message (max 16) |
| OPENZCA_LISTEN_MEDIA_FETCH_TIMEOUT_MS | 10000 | Max download time per media URL |
| OPENZCA_LISTEN_RECYCLE_MS | 1800000 | Force listener recycle after N ms (0 to disable) |
| OPENZCA_LISTEN_HEARTBEAT_MS | 30000 | Heartbeat interval for supervised mode |
| OPENZCA_LISTEN_INCLUDE_QUOTE_CONTEXT | 1 | Include reply context in content |
| OPENZCA_LISTEN_DOWNLOAD_QUOTE_MEDIA | 1 | Download quoted attachment URLs |
| OPENZCA_LISTEN_ENFORCE_SINGLE_OWNER | 1 | Enforce one listener per profile |
| OPENZCA_LISTEN_IPC | 1 | Expose IPC socket from listener |
| OPENZCA_LISTEN_KEEPALIVE_RESTART_DELAY_MS | 2000 | Restart delay after close |
| Upload & IPC | ||
| OPENZCA_UPLOAD_IPC | 1 | Try upload via listener IPC first |
| OPENZCA_UPLOAD_IPC_CONNECT_TIMEOUT_MS | 1000 | IPC connect timeout |
| OPENZCA_UPLOAD_IPC_TIMEOUT_MS | upload + 5000 | IPC response timeout |
| OPENZCA_UPLOAD_TIMEOUT_MS | 120000 | File upload timeout |
| OPENZCA_UPLOAD_ENFORCE_SINGLE_OWNER | 1 | Fail if listener owner exists but IPC unavailable |
| OPENZCA_UPLOAD_AUTO_THREAD_TYPE | 0 | Auto-detect thread type for uploads |
| Message History | ||
| OPENZCA_RECENT_USER_MAX_PAGES | 20 | Max websocket pages for DM recent |
| OPENZCA_RECENT_GROUP_MAX_PAGES | 20 | Max websocket pages for group recent |
| System | ||
| OPENZCA_SIGNAL_FORCE_EXIT_MS | 1500 | Force exit after signal timeout |
Data storage paths
File structure
# Default data directory (override with OPENZCA_HOME)
~/.openzca/
profiles.json # Profile registry
logs/openzca-debug.log # Debug log
profiles/<name>/
credentials.json # Auth credentials
cache/
friends.json # Friends cache
groups.json # Groups cache
meta.json # Cache metadata
db.json # DB config
messages.sqlite # SQLite database
listener-owner.json # Listener lock file
listen.sock # IPC socket