wacli

https://github.com/steipete/wacli
Admin
A WhatsApp CLI tool built on whatsmeow that enables local message history sync, fast offline search,...
Tokens:13,387
Snippets:98
Trust Score:10
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run Diagnostics

Source: https://github.com/steipete/wacli/blob/main/README.md

Performs diagnostic checks on the wacli setup to identify potential issues.

```bash
pnpm wacli doctor
```

--------------------------------

### Diagnostics API

Source: https://context7.com/steipete/wacli/llms.txt

Run system diagnostics to check the status of the WACLI installation and connection.

```APIDOC
## GET /api/doctor

### Description
Runs diagnostics to check store directory, authentication status, lock state, and FTS5 availability.

### Method
GET

### Endpoint
/api/doctor

### Parameters
#### Query Parameters
- **connect** (boolean) - Optional - Also test WhatsApp connection.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Basic diagnostics
wacli doctor

# Also test WhatsApp connection
wacli doctor --connect

# JSON output
wacli doctor --json
```

### Response
#### Success Response (200)
- **store_dir** (string) - Path to the store directory.
- **lock_held** (boolean) - Indicates if the lock is held.
- **authenticated** (boolean) - Indicates if the user is authenticated.
- **connected** (boolean) - Indicates if connected to WhatsApp.
- **fts_enabled** (boolean) - Indicates if FTS5 is enabled.

#### Response Example
```json
{
  "store_dir": "/home/user/.wacli",
  "lock_held": false,
  "authenticated": true,
  "connected": false,
  "fts_enabled": true
}
```
```

--------------------------------

### Get Group Information

Source: https://context7.com/steipete/wacli/llms.txt

Fetch and update detailed information for a specific group.

```bash
# Get group info
wacli groups info --jid 123456789@g.us

# JSON output
wacli groups info --jid 123456789@g.us --json
```

--------------------------------

### Groups API

Source: https://context7.com/steipete/wacli/llms.txt

Manage WhatsApp groups, including listing, refreshing, getting info, renaming, managing participants, and handling invite links.

```APIDOC
## GET /api/groups/list

### Description
Lists known groups from the local database.

### Method
GET

### Endpoint
/api/groups/list

### Parameters
#### Query Parameters
- **query** (string) - Optional - Search query to filter groups.
- **limit** (integer) - Optional - Maximum number of groups to return.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# List groups
wacli groups list

# Search groups
wacli groups list --query "project"

# Limit results
wacli groups list --limit 20

# JSON output
wacli groups list --json
```

## POST /api/groups/refresh

### Description
Fetches joined groups from WhatsApp (live) and updates the local database.

### Method
POST

### Endpoint
/api/groups/refresh

### Parameters
#### Query Parameters
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Refresh groups
wacli groups refresh

# JSON output
wacli groups refresh --json
```

### Response
#### Success Response (200)
- **groups** (integer) - The number of groups fetched.

#### Response Example
```json
{
  "groups": 25
}
```

## GET /api/groups/info

### Description
Fetches detailed group information from WhatsApp and updates the local database.

### Method
GET

### Endpoint
/api/groups/info

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Get group info
wacli groups info --jid 123456789@g.us

# JSON output
wacli groups info --jid 123456789@g.us --json
```

## PUT /api/groups/rename

### Description
Changes the name of a WhatsApp group (requires admin permissions).

### Method
PUT

### Endpoint
/api/groups/rename

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **name** (string) - Required - The new name for the group.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Rename group
wacli groups rename --jid 123456789@g.us --name "New Project Name"

# JSON output
wacli groups rename --jid 123456789@g.us --name "Team Alpha" --json
```

### Response
#### Success Response (200)
- **jid** (string) - The JID of the group.
- **name** (string) - The new name of the group.

#### Response Example
```json
{
  "jid": "123456789@g.us",
  "name": "Team Alpha"
}
```

## POST /api/groups/participants/add

### Description
Adds participants to a group.

### Method
POST

### Endpoint
/api/groups/participants/add

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **user** (string) - Required - JID(s) of the user(s) to add. Can be specified multiple times.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Add participants
wacli groups participants add --jid 123456789@g.us --user 1234567890 --user 0987654321

# JSON output
wacli groups participants add --jid 123456789@g.us --user 1234567890 --json
```

## DELETE /api/groups/participants/remove

### Description
Removes participants from a group.

### Method
DELETE

### Endpoint
/api/groups/participants/remove

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **user** (string) - Required - JID(s) of the user(s) to remove. Can be specified multiple times.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Remove participants
wacli groups participants remove --jid 123456789@g.us --user 1234567890
```

## POST /api/groups/participants/promote

### Description
Promotes participants to admin in a group.

### Method
POST

### Endpoint
/api/groups/participants/promote

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **user** (string) - Required - JID(s) of the user(s) to promote. Can be specified multiple times.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Promote to admin
wacli groups participants promote --jid 123456789@g.us --user 1234567890
```

## POST /api/groups/participants/demote

### Description
Demotes participants from admin in a group.

### Method
POST

### Endpoint
/api/groups/participants/demote

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **user** (string) - Required - JID(s) of the user(s) to demote. Can be specified multiple times.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Demote from admin
wacli groups participants demote --jid 123456789@g.us --user 1234567890
```

## GET /api/groups/invite_link/get

### Description
Gets the invite link for a group.

### Method
GET

### Endpoint
/api/groups/invite_link/get

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Get invite link
wacli groups invite link get --jid 123456789@g.us

# JSON output
wacli groups invite link get --jid 123456789@g.us --json
```

### Response
#### Success Response (200)
- **jid** (string) - The JID of the group.
- **link** (string) - The invite link.

#### Response Example
```json
{
  "jid": "123456789@g.us",
  "link": "https://chat.whatsapp.com/ABC123DEF456"
}
```

## POST /api/groups/invite_link/revoke

### Description
Revokes the current invite link and generates a new one for a group.

### Method
POST

### Endpoint
/api/groups/invite_link/revoke

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Revoke and get new invite link
wacli groups invite link revoke --jid 123456789@g.us
```

## POST /api/groups/join

### Description
Joins a group using an invite code extracted from an invite link.

### Method
POST

### Endpoint
/api/groups/join

### Parameters
#### Query Parameters
- **code** (string) - Required - The invite code for the group.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Join using invite code
wacli groups join --code ABC123DEF456

# JSON output
wacli groups join --code ABC123DEF456 --json
```

### Response
#### Success Response (200)
- **jid** (string) - The JID of the joined group.
- **joined** (boolean) - Indicates if the group was successfully joined.

#### Response Example
```json
{
  "jid": "123456789@g.us",
  "joined": true
}
```

## DELETE /api/groups/leave

### Description
Leaves a WhatsApp group.

### Method
DELETE

### Endpoint
/api/groups/leave

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the group to leave.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Leave group
wacli groups leave --jid 123456789@g.us

# JSON output
wacli groups leave --jid 123456789@g.us --json
```

### Response
#### Success Response (200)
- **jid** (string) - The JID of the group that was left.
- **left** (boolean) - Indicates if the group was successfully left.

#### Response Example
```json
{
  "jid": "123456789@g.us",
  "left": true
}
```
```

--------------------------------

### Chats API

Source: https://context7.com/steipete/wacli/llms.txt

Manage and retrieve chat information. List all chats, search, or get details for a specific chat.

```APIDOC
## GET /api/chats/list

### Description
Lists all chats from the local database, sorted by last message timestamp.

### Method
GET

### Endpoint
/api/chats/list

### Parameters
#### Query Parameters
- **query** (string) - Optional - Search query to filter chats.
- **limit** (integer) - Optional - Maximum number of chats to return (default: 50).
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# List chats (default limit: 50)
wacli chats list

# Search chats
wacli chats list --query "family"

# Custom limit
wacli chats list --limit 100

# JSON output
wacli chats list --json
```

## GET /api/chats/show

### Description
Displays detailed information about a specific chat.

### Method
GET

### Endpoint
/api/chats/show

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the chat to show.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example
```bash
# Show chat details
wacli chats show --jid 1234567890@s.whatsapp.net

# JSON output
wacli chats show --jid 1234567890@s.whatsapp.net --json
```
```

--------------------------------

### Authenticate and Bootstrap Sync

Source: https://context7.com/steipete/wacli/llms.txt

Authenticates the session via QR code and performs an initial sync. Use --follow to maintain a continuous connection.

```bash
# Basic authentication - shows QR, syncs, then exits
wacli auth

# Authenticate and keep syncing continuously
wacli auth --follow

# Custom idle timeout before exit (default: 30s)
wacli auth --idle-exit 60s

# Download media during bootstrap sync
wacli auth --download-media

# JSON output for scripting
wacli auth --json
# Output: {"authenticated":true,"messages_stored":1523}
```

--------------------------------

### Authenticate and Bootstrap Sync

Source: https://github.com/steipete/wacli/blob/main/README.md

Initiates the authentication process, which displays a QR code for logging in, and then bootstraps the initial data synchronization. This command requires prior authentication.

```bash
pnpm wacli auth
```

```bash
./dist/wacli auth
```

--------------------------------

### Build wacli Locally

Source: https://github.com/steipete/wacli/blob/main/README.md

Builds the wacli application locally. Use the `-tags sqlite_fts5` flag for SQLite full-text search support. The output binary is placed in the `dist/` directory.

```bash
go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli
```

--------------------------------

### Run System Diagnostics

Source: https://context7.com/steipete/wacli/llms.txt

Check system health, including store directory, authentication, and connection status.

```bash
# Basic diagnostics
wacli doctor

# Also test WhatsApp connection
wacli doctor --connect

# JSON output
wacli doctor --json
```

--------------------------------

### Run wacli After Local Build

Source: https://github.com/steipete/wacli/blob/main/README.md

Executes the wacli binary after a successful local build. Use the `--help` flag to see all available commands and options.

```bash
./dist/wacli --help
```

--------------------------------

### Tag and Push Release

Source: https://github.com/steipete/wacli/blob/main/docs/release.md

Commands to initiate a new release by tagging the repository and pushing the tag to GitHub.

```bash
git tag vX.Y.Z
```

```bash
git push origin vX.Y.Z
```

--------------------------------

### Global CLI Options

Source: https://context7.com/steipete/wacli/llms.txt

Common flags applicable to most wacli commands for configuration and output control.

```bash
# Custom store directory (default: ~/.wacli)
wacli --store /path/to/store chats list

# JSON output for scripting
wacli --json messages list

# Custom command timeout (default: 5m, does not apply to sync)
wacli --timeout 10m contacts refresh

# Show version
wacli --version
```

--------------------------------

### Join Group by Invite

Source: https://context7.com/steipete/wacli/llms.txt

Join a group using an invite code.

```bash
# Join using invite code
wacli groups join --code ABC123DEF456

# JSON output
wacli groups join --code ABC123DEF456 --json
```

--------------------------------

### List and Search Groups

Source: https://context7.com/steipete/wacli/llms.txt

Retrieve known groups from the local database with optional search queries and result limits.

```bash
# List groups
wacli groups list

# Search groups
wacli groups list --query "project"

# Limit results
wacli groups list --limit 20

# JSON output
wacli groups list --json
```

--------------------------------

### Send Files and Media

Source: https://context7.com/steipete/wacli/llms.txt

Send files with optional captions, filename overrides, or custom MIME types.

```bash
wacli send file --to 1234567890 --file ./photo.jpg --caption "Check this out!"

wacli send file --to 1234567890 --file ./report.pdf

wacli send file --to 1234567890 --file /tmp/abc123 --filename report.pdf

wacli send file --to 1234567890 --file ./data.bin --mime application/octet-stream

wacli send file --to 1234567890 --file ./photo.jpg --json
```

--------------------------------

### Show Contact Details

Source: https://context7.com/steipete/wacli/llms.txt

Display detailed information for a specific contact by JID.

```bash
wacli contacts show --jid 1234567890@s.whatsapp.net

wacli contacts show --jid 1234567890@s.whatsapp.net --json
```

--------------------------------

### Refresh Contacts

Source: https://context7.com/steipete/wacli/llms.txt

Import contacts from the WhatsApp session store into the local database.

```bash
wacli contacts refresh

wacli contacts refresh --json
```

--------------------------------

### Global Options

Source: https://context7.com/steipete/wacli/llms.txt

Global options applicable to all WACLI commands.

```APIDOC
## Global Options

All commands support these global flags:

### Parameters
#### Query Parameters
- **store** (string) - Optional - Custom store directory (default: `~/.wacli`).
- **json** (boolean) - Optional - Output in JSON format for scripting.
- **timeout** (string) - Optional - Custom command timeout (default: `5m`, does not apply to sync). Example: `10m`.
- **version** (boolean) - Optional - Show version information.

### Request Example
```bash
# Custom store directory
wacli --store /path/to/store chats list

# JSON output for scripting
wacli --json messages list

# Custom command timeout
wacli --timeout 10m contacts refresh

# Show version
wacli --version
```
```

--------------------------------

### Download Message Media

Source: https://context7.com/steipete/wacli/llms.txt

Download media attachments to a specified location or the default directory.

```bash
wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456

wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --output ./downloads/

wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --output ./photo.jpg

wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

--------------------------------

### List Groups

Source: https://github.com/steipete/wacli/blob/main/README.md

Lists all groups that wacli is a part of.

```bash
pnpm wacli groups list
```

--------------------------------

### List Messages

Source: https://context7.com/steipete/wacli/llms.txt

Retrieves messages from the local database with filtering options.

```bash
# List recent messages (default limit: 50)
wacli messages list

# List messages from specific chat
wacli messages list --chat 1234567890@s.whatsapp.net

# Limit results
wacli messages list --limit 100

# Filter by time range (RFC3339 or YYYY-MM-DD)
wacli messages list --after 2024-01-01 --before 2024-06-30

# JSON output
wacli messages list --chat 1234567890@s.whatsapp.net --json
# Output: {"messages":[{"ChatJID":"1234567890@s.whatsapp.net","MsgID":"abc123","SenderJID":"1234567890@s.whatsapp.net","Timestamp":"2024-01-15T10:30:00Z","FromMe":false,"Text":"Hello!"}],"fts":true}
```

--------------------------------

### Show Chat Details

Source: https://context7.com/steipete/wacli/llms.txt

Display detailed information for a specific chat identified by its JID.

```bash
# Show chat details
wacli chats show --jid 1234567890@s.whatsapp.net

# JSON output
wacli chats show --jid 1234567890@s.whatsapp.net --json
```

--------------------------------

### wacli auth

Source: https://context7.com/steipete/wacli/llms.txt

Authenticates with WhatsApp via QR code and performs an initial sync of message history and metadata.

```APIDOC
## wacli auth

### Description
Authenticates with WhatsApp by displaying a QR code for scanning with the WhatsApp mobile app. Performs an initial sync upon success.

### Parameters
#### Options
- **--follow** (flag) - Optional - Keep syncing continuously after authentication.
- **--idle-exit** (duration) - Optional - Custom idle timeout before exit (default: 30s).
- **--download-media** (flag) - Optional - Download media during bootstrap sync.
- **--json** (flag) - Optional - Output result in JSON format.

### Response Example
{"authenticated":true,"messages_stored":1523}
```

--------------------------------

### Manage Group Participants

Source: https://context7.com/steipete/wacli/llms.txt

Perform administrative actions on group participants including adding, removing, promoting, or demoting.

```bash
# Add participants
wacli groups participants add --jid 123456789@g.us --user 1234567890 --user 0987654321

# Remove participants
wacli groups participants remove --jid 123456789@g.us --user 1234567890

# Promote to admin
wacli groups participants promote --jid 123456789@g.us --user 1234567890

# Demote from admin
wacli groups participants demote --jid 123456789@g.us --user 1234567890

# JSON output
wacli groups participants add --jid 123456789@g.us --user 1234567890 --json
```

--------------------------------

### List and Search Chats

Source: https://context7.com/steipete/wacli/llms.txt

Retrieve chats from the local database with options for filtering and output formatting.

```bash
# List chats (default limit: 50)
wacli chats list

# Search chats
wacli chats list --query "family"

# Custom limit
wacli chats list --limit 100

# JSON output
wacli chats list --json
```

--------------------------------

### Manage Invite Links

Source: https://context7.com/steipete/wacli/llms.txt

Retrieve or revoke group invite links.

```bash
# Get invite link
wacli groups invite link get --jid 123456789@g.us

# Revoke and get new invite link
wacli groups invite link revoke --jid 123456789@g.us

# JSON output
wacli groups invite link get --jid 123456789@g.us --json
```

--------------------------------

### Continuous Sync

Source: https://github.com/steipete/wacli/blob/main/README.md

Keeps the WhatsApp data continuously synchronized in the background. This command does not display the QR code and requires prior authentication.

```bash
pnpm wacli sync --follow
```

--------------------------------

### Leave Group

Source: https://context7.com/steipete/wacli/llms.txt

Exit a WhatsApp group.

```bash
# Leave group
wacli groups leave --jid 123456789@g.us

# JSON output
wacli groups leave --jid 123456789@g.us --json
```

--------------------------------

### Show Message Details

Source: https://context7.com/steipete/wacli/llms.txt

Retrieve detailed information for a specific message using its chat JID and message ID.

```bash
wacli messages show --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456

wacli messages show --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

--------------------------------

### Show Message Context

Source: https://context7.com/steipete/wacli/llms.txt

Display messages surrounding a specific message to provide conversation context.

```bash
wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456

wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --before 10 --after 3

wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

--------------------------------

### Search Contacts

Source: https://context7.com/steipete/wacli/llms.txt

Search through synced contacts in the local database.

```bash
wacli contacts search "john"

wacli contacts search "smith" --limit 10

wacli contacts search "john" --json
```

--------------------------------

### wacli sync

Source: https://context7.com/steipete/wacli/llms.txt

Performs continuous message synchronization from WhatsApp without requiring QR authentication.

```APIDOC
## wacli sync

### Description
Syncs messages from WhatsApp for background processes and daemons.

### Parameters
#### Options
- **--once** (flag) - Optional - Sync once and exit after idle timeout.
- **--follow** (flag) - Optional - Continuous sync until interrupted.
- **--download-media** (flag) - Optional - Sync with media download enabled.
- **--refresh-contacts** (flag) - Optional - Refresh contacts during sync.
- **--refresh-groups** (flag) - Optional - Refresh groups during sync.
- **--max-reconnect** (duration) - Optional - Custom reconnection timeout (default: 5m).
- **--json** (flag) - Optional - Output result in JSON format.

### Response Example
{"synced":true,"messages_stored":42}
```

--------------------------------

### Manage Contact Aliases

Source: https://context7.com/steipete/wacli/llms.txt

Set or remove local aliases for contacts, which are stored locally and not synced to WhatsApp.

```bash
wacli contacts alias set --jid 1234567890@s.whatsapp.net --alias "John Work"

wacli contacts alias rm --jid 1234567890@s.whatsapp.net

wacli contacts alias set --jid 1234567890@s.whatsapp.net --alias "John" --json
```

--------------------------------

### Backfill All Chats Script

Source: https://github.com/steipete/wacli/blob/main/README.md

A script to backfill history for all chats known in the local database. It lists all chats, extracts their JIDs, and then calls the history backfill command for each.

```bash
pnpm -s wacli -- --json chats list --limit 100000 \
  | jq -r '.[].JID' \
  | while read -r jid; do
      pnpm -s wacli -- history backfill --chat "$jid" --requests 3 --count 50
    done
```

--------------------------------

### Refresh Group Data

Source: https://context7.com/steipete/wacli/llms.txt

Synchronize joined groups from WhatsApp to the local database.

```bash
# Refresh groups
wacli groups refresh

# JSON output
wacli groups refresh --json
```

--------------------------------

### wacli contacts refresh - Import Contacts

Source: https://context7.com/steipete/wacli/llms.txt

Imports contacts from the WhatsApp session store into the local database. Supports JSON output.

```APIDOC
### wacli contacts refresh - Import Contacts

### Description
Imports contacts from the WhatsApp session store into the local database. Supports JSON output.

### Method
POST

### Endpoint
/contacts/refresh

### Parameters
#### Query Parameters
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli contacts refresh
wacli contacts refresh --json
```

### Response
#### Success Response (200)
- **contacts** (integer) - The number of contacts imported.

#### Response Example
```json
{
  "contacts": 150
}
```
```

--------------------------------

### Download Message Media

Source: https://github.com/steipete/wacli/blob/main/README.md

Downloads the media associated with a specific message after it has been synced. Requires the chat JID and message ID.

```bash
./wacli media download --chat 1234567890@s.whatsapp.net --id <message-id>
```

--------------------------------

### Rename Group

Source: https://context7.com/steipete/wacli/llms.txt

Update the name of a WhatsApp group, requiring admin permissions.

```bash
# Rename group
wacli groups rename --jid 123456789@g.us --name "New Project Name"

# JSON output
wacli groups rename --jid 123456789@g.us --name "Team Alpha" --json
```

--------------------------------

### Check Authentication Status

Source: https://context7.com/steipete/wacli/llms.txt

Verifies if a valid session exists locally without network interaction.

```bash
# Check authentication status
wacli auth status

# JSON output
wacli auth status --json
# Output: {"authenticated":true}
```

--------------------------------

### Manage Contact Tags

Source: https://context7.com/steipete/wacli/llms.txt

Add or remove tags from a specific contact using their JID.

```bash
wacli contacts tags add --jid 1234567890@s.whatsapp.net --tag "work"
```

```bash
wacli contacts tags rm --jid 1234567890@s.whatsapp.net --tag "work"
```

```bash
wacli contacts tags add --jid 1234567890@s.whatsapp.net --tag "vip" --json
```

--------------------------------

### Search Messages with wacli

Source: https://context7.com/steipete/wacli/llms.txt

Search local message history with filters for media type, time range, and result limits.

```bash
wacli messages search "report" --type document

wacli messages search "deadline" --after 2024-01-01 --before 2024-03-31

wacli messages search "urgent" --limit 20

wacli messages search "meeting" --json
```

--------------------------------

### Group Management

Source: https://github.com/steipete/wacli/blob/main/docs/spec.md

Manage group participants and settings.

```APIDOC
## POST wacli groups participants add

### Description
Adds participants to a group.

### Parameters
#### Query Parameters
- **--jid** (GROUP_JID) - Required - Group identifier
- **--user** (PHONE_OR_JID) - Required - User identifier(s) to add
```

--------------------------------

### Continuous Message Sync

Source: https://context7.com/steipete/wacli/llms.txt

Syncs messages in the background without QR prompts. Suitable for daemons.

```bash
# Sync once and exit after idle timeout
wacli sync --once

# Continuous sync until Ctrl+C (default)
wacli sync --follow

# Sync with media download enabled
wacli sync --download-media

# Refresh contacts and groups during sync
wacli sync --refresh-contacts --refresh-groups

# Custom reconnection timeout (default: 5m, 0 = unlimited)
wacli sync --max-reconnect 10m

# Custom idle exit for --once mode
wacli sync --once --idle-exit 60s

# JSON output
wacli sync --json
# Output: {"synced":true,"messages_stored":42}
```

--------------------------------

### Send File

Source: https://github.com/steipete/wacli/blob/main/README.md

Sends a file to a specified recipient. You can optionally override the displayed filename.

```bash
./wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
```

```bash
./wacli send file --to 1234567890 --file /tmp/abc123 --filename report.pdf
```

--------------------------------

### wacli contacts show - Show Contact Details

Source: https://context7.com/steipete/wacli/llms.txt

Displays detailed information about a specific contact using their JID. Supports JSON output.

```APIDOC
### wacli contacts show - Show Contact Details

### Description
Displays detailed information about a specific contact. Supports JSON output.

### Method
GET

### Endpoint
/contacts/show

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the contact.
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli contacts show --jid 1234567890@s.whatsapp.net
wacli contacts show --jid 1234567890@s.whatsapp.net --json
```

### Response
#### Success Response (200)
- **contact** (object) - Detailed information about the contact.
  - **JID** (string) - The JID of the contact.
  - **Name** (string) - The name of the contact.
  - **Number** (string) - The phone number of the contact.
  - **About** (string) - The 'about' information of the contact.
  - **Picture** (string) - URL to the contact's profile picture.
  - **IsBlocked** (boolean) - Indicates if the contact is blocked.

#### Response Example
```json
{
  "contact": {
    "JID": "1234567890@s.whatsapp.net",
    "Name": "John Doe",
    "Number": "1234567890",
    "About": "Available",
    "Picture": "https://example.com/pic.jpg",
    "IsBlocked": false
  }
}
```
```

--------------------------------

### Full-Text Search

Source: https://context7.com/steipete/wacli/llms.txt

Performs fast searches using SQLite FTS5, falling back to LIKE queries if necessary.

```bash
# Basic search
wacli messages search "meeting"

# Search within specific chat
wacli messages search "project" --chat 123456789@g.us

# Filter by sender
wacli messages search "invoice" --from 1234567890@s.whatsapp.net
```

--------------------------------

### wacli media download - Download Message Media

Source: https://context7.com/steipete/wacli/llms.txt

Downloads media attachments for a specific message. Requires synced media metadata and an active connection. Supports JSON output.

```APIDOC
## Media

### wacli media download - Download Message Media

### Description
Downloads media attachments for a specific message. Requires synced media metadata and an active connection. Supports JSON output.

### Method
GET

### Endpoint
/media/download

### Parameters
#### Query Parameters
- **chat** (string) - Required - The JID of the chat the message belongs to.
- **id** (string) - Required - The unique ID of the message containing the media.
- **output** (string) - Optional - The path to save the downloaded media. Can be a directory or a specific filename.
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456
wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --output ./downloads/
wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --output ./photo.jpg
wacli media download --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

### Response
#### Success Response (200)
- **chat** (string) - The JID of the chat.
- **id** (string) - The unique ID of the message.
- **path** (string) - The path where the media was saved.
- **bytes** (integer) - The size of the downloaded media in bytes.
- **media_type** (string) - The type of media (e.g., image, video, audio, document).
- **mime_type** (string) - The MIME type of the media.
- **downloaded** (boolean) - Indicates if the media was successfully downloaded.
- **downloaded_at** (string) - The timestamp when the media was downloaded.

#### Response Example
```json
{
  "chat": "1234567890@s.whatsapp.net",
  "id": "3EB0ABC123DEF456",
  "path": "/home/user/.wacli/media/photo.jpg",
  "bytes": 102400,
  "media_type": "image",
  "mime_type": "image/jpeg",
  "downloaded": true,
  "downloaded_at": "2024-01-15T10:30:00.123456789Z"
}
```
```

--------------------------------

### wacli messages show - Show Single Message

Source: https://context7.com/steipete/wacli/llms.txt

Displays detailed information about a specific message using its chat JID and message ID. Supports JSON output.

```APIDOC
## wacli messages show - Show Single Message

### Description
Displays detailed information about a specific message by chat JID and message ID. Supports JSON output.

### Method
GET

### Endpoint
/messages/show

### Parameters
#### Query Parameters
- **chat** (string) - Required - The JID of the chat the message belongs to.
- **id** (string) - Required - The unique ID of the message.
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli messages show --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456
wacli messages show --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

### Response
#### Success Response (200)
- **message** (object) - Detailed information about the message.
  - **ChatJID** (string) - The JID of the chat.
  - **MsgID** (string) - The unique ID of the message.
  - **Text** (string) - The content of the message.
  - **Timestamp** (string) - The timestamp of the message.
  - **Sender** (string) - The JID of the sender.
  - **Status** (string) - The status of the message.

#### Response Example
```json
{
  "message": {
    "ChatJID": "1234567890@s.whatsapp.net",
    "MsgID": "3EB0ABC123DEF456",
    "Text": "This is a test message.",
    "Timestamp": "2024-01-15T10:00:00Z",
    "Sender": "1234567890@s.whatsapp.net",
    "Status": "sent"
  }
}
```
```

--------------------------------

### wacli send file - Send File/Media

Source: https://context7.com/steipete/wacli/llms.txt

Sends a file (image, video, audio, or document) to a recipient with an optional caption. Automatically detects MIME type. Supports JSON output.

```APIDOC
### wacli send file - Send File/Media

### Description
Sends a file (image, video, audio, or document) to a recipient with optional caption. Automatically detects MIME type. Supports JSON output.

### Method
POST

### Endpoint
/send/file

### Parameters
#### Query Parameters
- **to** (string) - Required - The recipient's phone number or JID.
- **file** (string) - Required - The path to the file to send.
- **caption** (string) - Optional - A caption for the media file.
- **filename** (string) - Optional - Overrides the display filename.
- **mime** (string) - Optional - Overrides the detected MIME type.
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli send file --to 1234567890 --file ./photo.jpg --caption "Check this out!"
wacli send file --to 1234567890 --file ./report.pdf
wacli send file --to 1234567890 --file /tmp/abc123 --filename report.pdf
wacli send file --to 1234567890 --file ./data.bin --mime application/octet-stream
wacli send file --to 1234567890 --file ./photo.jpg --json
```

### Response
#### Success Response (200)
- **sent** (boolean) - Indicates if the file was successfully sent.
- **to** (string) - The recipient's JID.
- **id** (string) - The unique ID of the sent message.
- **file** (object) - Information about the sent file.
  - **name** (string) - The name of the file.
  - **size** (integer) - The size of the file in bytes.

#### Response Example
```json
{
  "sent": true,
  "to": "1234567890@s.whatsapp.net",
  "id": "3EB0XYZ789",
  "file": {
    "name": "photo.jpg",
    "size": 102400
  }
}
```
```

--------------------------------

### wacli messages context - Show Message Context

Source: https://context7.com/steipete/wacli/llms.txt

Displays messages surrounding a specific message to provide conversation context. Supports custom context window sizes and JSON output.

```APIDOC
## wacli messages context - Show Message Context

### Description
Displays messages surrounding a specific message to provide conversation context. Supports custom context window sizes and JSON output.

### Method
GET

### Endpoint
/messages/context

### Parameters
#### Query Parameters
- **chat** (string) - Required - The JID of the chat the message belongs to.
- **id** (string) - Required - The unique ID of the message.
- **before** (integer) - Optional - The number of messages to retrieve before the specified message (default is 5).
- **after** (integer) - Optional - The number of messages to retrieve after the specified message (default is 5).
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456
wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --before 10 --after 3
wacli messages context --chat 1234567890@s.whatsapp.net --id 3EB0ABC123DEF456 --json
```

### Response
#### Success Response (200)
- **messages** (array) - A list of message objects providing conversation context.
  - **ChatJID** (string) - The JID of the chat.
  - **MsgID** (string) - The unique ID of the message.
  - **Text** (string) - The content of the message.
  - **Timestamp** (string) - The timestamp of the message.
  - **Sender** (string) - The JID of the sender.

#### Response Example
```json
{
  "messages": [
    {
      "ChatJID": "1234567890@s.whatsapp.net",
      "MsgID": "PREV_MSG_ID",
      "Text": "Previous message content.",
      "Timestamp": "2024-01-15T09:55:00Z",
      "Sender": "ANOTHER_USER@s.whatsapp.net"
    },
    {
      "ChatJID": "1234567890@s.whatsapp.net",
      "MsgID": "3EB0ABC123DEF456",
      "Text": "Target message content.",
      "Timestamp": "2024-01-15T10:00:00Z",
      "Sender": "1234567890@s.whatsapp.net"
    },
    {
      "ChatJID": "1234567890@s.whatsapp.net",
      "MsgID": "NEXT_MSG_ID",
      "Text": "Next message content.",
      "Timestamp": "2024-01-15T10:05:00Z",
      "Sender": "ANOTHER_USER@s.whatsapp.net"
    }
  ]
}
```
```

--------------------------------

### wacli messages list

Source: https://context7.com/steipete/wacli/llms.txt

Lists messages from the local database with optional filtering by chat and time range.

```APIDOC
## wacli messages list

### Description
Retrieves messages from the local SQLite database.

### Parameters
#### Options
- **--chat** (string) - Optional - Filter by specific chat JID.
- **--limit** (integer) - Optional - Limit number of results (default: 50).
- **--after** (string) - Optional - Filter messages after this date (RFC3339/YYYY-MM-DD).
- **--before** (string) - Optional - Filter messages before this date (RFC3339/YYYY-MM-DD).
- **--json** (flag) - Optional - Output result in JSON format.

### Response Example
{"messages":[{"ChatJID":"1234567890@s.whatsapp.net","MsgID":"abc123","SenderJID":"1234567890@s.whatsapp.net","Timestamp":"2024-01-15T10:30:00Z","FromMe":false,"Text":"Hello!"}],"fts":true}
```

--------------------------------

### Fetch Older Messages

Source: https://context7.com/steipete/wacli/llms.txt

Requests historical messages for a specific chat from the primary device.

```bash
# Basic backfill for a DM chat
wacli history backfill --chat 1234567890@s.whatsapp.net

# Request more messages (default: 50 per request)
wacli history backfill --chat 1234567890@s.whatsapp.net --count 100

# Multiple backfill requests (default: 1)
wacli history backfill --chat 123456789@g.us --requests 10 --count 50

# Custom wait timeout per request (default: 60s)
wacli history backfill --chat 1234567890@s.whatsapp.net --wait 120s

# JSON output
wacli history backfill --chat 1234567890@s.whatsapp.net --json
# Output: {"chat":"1234567890@s.whatsapp.net","requests_sent":1,"responses_seen":1,"messages_added":47,"messages_synced":47}

# Backfill all chats (shell script)
wacli --json chats list --limit 100000 | jq -r '.[].JID' | while read -r jid; do
    wacli history backfill --chat "$jid" --requests 3 --count 50
done
```

--------------------------------

### Search Messages

Source: https://github.com/steipete/wacli/blob/main/README.md

Searches for messages containing a specific keyword. The search is performed on the locally synced message history.

```bash
pnpm wacli messages search "meeting"
```

--------------------------------

### Backfill Chat History

Source: https://github.com/steipete/wacli/blob/main/README.md

Attempts to backfill older messages for a specific chat. This requires the primary device to be online and is a best-effort operation.

```bash
pnpm wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50
```

--------------------------------

### wacli contacts tags - Manage Contact Tags

Source: https://context7.com/steipete/wacli/llms.txt

Adds or removes local tags for contacts. Tags are stored locally for organization.

```APIDOC
### wacli contacts tags - Manage Contact Tags

### Description
Adds or removes local tags for contacts (stored locally for organization).

### Method
POST

### Endpoint
/contacts/tags

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the contact.
- **tag** (string) - Required - The tag to add or remove.
- **action** (string) - Required - The action to perform: 'add' or 'remove'.

### Request Example
```bash
# Add tag
wacli contacts tags add --jid 1234567890@s.whatsapp.net --tag "important"
# Remove tag
wacli contacts tags remove --jid 1234567890@s.whatsapp.net --tag "important"
```

### Response
#### Success Response (200)
- **status** (string) - Confirmation message of the action performed.

#### Response Example
```json
{
  "status": "Tag 'important' added to contact 1234567890@s.whatsapp.net"
}
```
```

--------------------------------

### wacli contacts alias - Manage Local Aliases

Source: https://context7.com/steipete/wacli/llms.txt

Sets or removes local aliases for contacts. Aliases are stored locally and are not synced to WhatsApp. Supports JSON output.

```APIDOC
### wacli contacts alias - Manage Local Aliases

### Description
Sets or removes local aliases for contacts (stored locally, not synced to WhatsApp). Supports JSON output.

### Method
POST

### Endpoint
/contacts/alias

### Parameters
#### Query Parameters
- **jid** (string) - Required - The JID of the contact.
- **alias** (string) - Required (for set) - The alias to set for the contact.
- **action** (string) - Required - The action to perform: 'set' or 'rm'.
- **json** (boolean) - Optional - Outputs the results in JSON format.

### Request Example
```bash
# Set alias
wacli contacts alias set --jid 1234567890@s.whatsapp.net --alias "John Work"
# Remove alias
wacli contacts alias rm --jid 1234567890@s.whatsapp.net
# JSON output for setting alias
wacli contacts alias set --jid 1234567890@s.whatsapp.net --alias "John" --json
```

### Response
#### Success Response (200)
- **jid** (string) - The JID of the contact.
- **alias** (string) - The alias that was set or removed.

#### Response Example
```json
{
  "jid": "1234567890@s.whatsapp.net",
  "alias": "John"
}
```
```

--------------------------------

### Send Text Messages

Source: https://context7.com/steipete/wacli/llms.txt

Send text messages to phone numbers, JIDs, or groups. Messages are automatically stored in the local database.

```bash
wacli send text --to 1234567890 --message "Hello, world!"

wacli send text --to 1234567890@s.whatsapp.net --message "Hello!"

wacli send text --to 123456789@g.us --message "Hello everyone!"

wacli send text --to 1234567890 --message "Hi" --json
```

--------------------------------

### Send Text Message

Source: https://github.com/steipete/wacli/blob/main/README.md

Sends a text message to a specified recipient. Requires the recipient's JID and the message content.

```bash
pnpm wacli send text --to 1234567890 --message "hello"
```
Tokens:
Raw