docs: add hosted documentation pages
This commit is contained in:
Peter Steinberger
parent
0826cd4aa1
commit
b974645fdb
@ -12,10 +12,12 @@ This is a third-party tool that uses the WhatsApp Web protocol via `whatsmeow` a
|
||||
|
||||
## Status
|
||||
|
||||
Core implementation is in place. Start with [docs/overview.md](docs/overview.md) for the command map and [docs/spec.md](docs/spec.md) for design notes.
|
||||
Core implementation is in place. The full documentation site lives at [wacli.sh](https://wacli.sh). Start with [docs/overview.md](docs/overview.md) for the command map and [docs/spec.md](docs/spec.md) for design notes.
|
||||
|
||||
## Documentation
|
||||
|
||||
Full docs site: <https://wacli.sh>.
|
||||
|
||||
- [Overview](docs/overview.md): store model, global flags, common flow, command index.
|
||||
- [Auth](docs/auth.md): `auth`, `auth status`, `auth logout`.
|
||||
- [Sync](docs/sync.md): `sync --once`, `sync --follow`, refresh, media download.
|
||||
|
||||
1
docs/CNAME
Normal file
1
docs/CNAME
Normal file
@ -0,0 +1 @@
|
||||
wacli.sh
|
||||
42
docs/index.md
Normal file
42
docs/index.md
Normal file
@ -0,0 +1,42 @@
|
||||
---
|
||||
title: Overview
|
||||
permalink: /
|
||||
description: "wacli is a single Go CLI that pairs as a linked WhatsApp Web device, mirrors message history into local SQLite with FTS5 search, and exposes send, media, contact, and group workflows for terminals, scripts, and coding agents."
|
||||
---
|
||||
|
||||
# wacli
|
||||
|
||||
A script-friendly WhatsApp CLI built on [`whatsmeow`](https://github.com/tulir/whatsmeow). One binary pairs as a linked WhatsApp Web device, syncs messages into a local SQLite store, and exposes search, send, media, contact, and group commands with predictable output for terminals, shell pipelines, and coding agents.
|
||||
|
||||
## Why wacli
|
||||
|
||||
- **Local mirror, fast search.** All synced messages land in a SQLite store with an FTS5 index; offline `messages search` returns hits in milliseconds.
|
||||
- **Stable output.** Human-readable tables by default, `--json` to stdout for scripts, NDJSON `--events` for long-running commands. Human progress, prompts, and errors stay on stderr so pipes stay clean.
|
||||
- **Single binary.** No daemon, no plugin host. Run `wacli auth`, then `wacli sync --follow` to keep the store warm.
|
||||
- **Built for agents.** `--read-only` (or `WACLI_READONLY=1`) blocks every command that mutates WhatsApp or local state. Store locks prevent two instances from racing on the same device identity.
|
||||
- **Boundable storage.** `sync` warns when storage is uncapped; `--max-messages` / `--max-db-size` cap local growth. Send retries are bounded; media uploads/downloads cap at 100 MiB.
|
||||
- **Best-effort history.** `history backfill` requests older messages per chat from your primary device; documented as best-effort because WhatsApp Web is.
|
||||
|
||||
## Pick your path
|
||||
|
||||
- **Trying it.** Read [Install](install.md), then [Quickstart](quickstart.md). Pair, sync, and send your first message in under five minutes.
|
||||
- **Searching old chats.** Read [Sync](sync.md) for the sync model and [History](history.md) for on-demand backfill.
|
||||
- **Sending from scripts.** Read [Send](send.md) for recipient resolution, replies, mentions, files, and reactions.
|
||||
- **Wiring up an agent.** Pair `--read-only`, `--json`, and `--events` from [Overview](overview.md); read [Doctor](doctor.md) for self-checks.
|
||||
- **Looking up a flag.** Open the per-command pages from [Overview](overview.md).
|
||||
|
||||
## Status
|
||||
|
||||
Core implementation is in place. The [CHANGELOG](https://github.com/steipete/wacli/blob/main/CHANGELOG.md) tracks shipped behavior. WhatsApp Web is not a published API; expect occasional breakage from upstream protocol changes — `wacli` follows `whatsmeow` upstream.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Guaranteed full-history export (WhatsApp Web history is best-effort).
|
||||
- A daemon, MCP server, web UI, or GUI.
|
||||
- End-to-end "contact creation" inside WhatsApp; local aliases and tags only.
|
||||
|
||||
## Disclaimer
|
||||
|
||||
`wacli` is a third-party tool that uses the WhatsApp Web protocol via `whatsmeow`. It is **not affiliated with WhatsApp or Meta**. Use at your own risk; pairing as a linked device is subject to WhatsApp's terms.
|
||||
|
||||
Released under the [MIT license](https://github.com/steipete/wacli/blob/main/LICENSE).
|
||||
83
docs/install.md
Normal file
83
docs/install.md
Normal file
@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Install
|
||||
description: "Install wacli via Homebrew tap, prebuilt release archives, or a local build with cgo."
|
||||
---
|
||||
|
||||
# Install
|
||||
|
||||
`wacli` ships as a single binary. Local builds need cgo (because of `go-sqlite3` with FTS5); release artifacts and the Homebrew tap take care of that for you.
|
||||
|
||||
## Homebrew (macOS, Linux)
|
||||
|
||||
```bash
|
||||
brew install steipete/tap/wacli
|
||||
wacli --version
|
||||
```
|
||||
|
||||
If a Linux install from the tap reports `Binary was compiled with 'CGO_ENABLED=0'`, update the tap and reinstall the formula:
|
||||
|
||||
```bash
|
||||
brew update
|
||||
brew reinstall steipete/tap/wacli
|
||||
```
|
||||
|
||||
## GitHub releases (raw binaries)
|
||||
|
||||
Download the matching archive from the [latest release](https://github.com/steipete/wacli/releases) and put `wacli` (or `wacli.exe` on Windows) on your `PATH`.
|
||||
|
||||
## Build from source
|
||||
|
||||
`wacli` uses `go-sqlite3`, so source builds require cgo and a C toolchain:
|
||||
|
||||
- macOS: Xcode Command Line Tools.
|
||||
- Debian / Ubuntu: `sudo apt install build-essential`.
|
||||
- Fedora / RHEL: `sudo dnf groupinstall "Development Tools"`.
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/steipete/wacli.git
|
||||
cd wacli
|
||||
CGO_ENABLED=1 CGO_CFLAGS="-Wno-error=missing-braces" \
|
||||
go build -tags sqlite_fts5 -o ./dist/wacli ./cmd/wacli
|
||||
./dist/wacli --version
|
||||
```
|
||||
|
||||
The `sqlite_fts5` build tag is required for `messages search` to use the FTS5 index. Without it, search falls back to `LIKE`.
|
||||
|
||||
GCC 15 has stricter brace-init warnings; the `-Wno-error=missing-braces` flag keeps the `go-sqlite3` build green there. macOS / clang and older GCC do not need it.
|
||||
|
||||
If you have `pnpm` installed, `pnpm build` runs the same command and writes `./dist/wacli`.
|
||||
|
||||
## Verify the install
|
||||
|
||||
```bash
|
||||
wacli --version
|
||||
wacli doctor
|
||||
wacli --help
|
||||
```
|
||||
|
||||
`wacli doctor` checks the store directory, database integrity, FTS5 availability, and (with `--connect`) live connectivity to WhatsApp. See [Doctor](doctor.md).
|
||||
|
||||
## Updating
|
||||
|
||||
- **Homebrew tap**: `brew upgrade wacli` (or `brew reinstall steipete/tap/wacli`).
|
||||
- **GitHub release archives**: download the new tarball / ZIP and replace the binary.
|
||||
- **Source builds**: `git pull && pnpm build` (or the manual `go build` above). Local builds use the version compiled into the source tree; release artifacts inject the tag during GoReleaser builds.
|
||||
|
||||
The local store format is forward-compatible across point releases; routine upgrades do not require re-pairing.
|
||||
|
||||
## Storage
|
||||
|
||||
- Default store directory: `~/.local/state/wacli` on Linux (XDG state dir), `~/.wacli` on macOS / Windows. Existing Linux `~/.wacli` directories keep working.
|
||||
- Override with `--store DIR` or `WACLI_STORE_DIR`.
|
||||
- The store contains `session.db` (whatsmeow keys), `wacli.db` (messages + FTS), `media/`, and a `LOCK` file. See [Spec](spec.md#storage-layout) for the layout.
|
||||
- Permissions are owner-only (`0700` on the directory, `0600` on files). Do not relax these — they protect your WhatsApp session keys.
|
||||
|
||||
## Related pages
|
||||
|
||||
- [Quickstart](quickstart.md) — pair, sync, and send your first message.
|
||||
- [Auth](auth.md) — `wacli auth`, `auth status`, `auth logout`.
|
||||
- [Sync](sync.md) — bootstrap and follow-mode sync, refresh flags.
|
||||
- [Doctor](doctor.md) — self-checks and connectivity probe.
|
||||
- [Release](release.md) — release workflow and artifact expectations.
|
||||
126
docs/quickstart.md
Normal file
126
docs/quickstart.md
Normal file
@ -0,0 +1,126 @@
|
||||
---
|
||||
title: Quickstart
|
||||
description: "Pair as a linked WhatsApp Web device, sync, search, and send your first message in under five minutes."
|
||||
---
|
||||
|
||||
# Quickstart
|
||||
|
||||
Five minutes from a clean machine to authenticated sync, search, and send. For deeper reading, follow the links at the bottom of each step.
|
||||
|
||||
## 1. Install
|
||||
|
||||
```bash
|
||||
brew install steipete/tap/wacli
|
||||
wacli --version
|
||||
```
|
||||
|
||||
Other options (release archives, source builds, GCC 15 notes) are documented on [Install](install.md).
|
||||
|
||||
## 2. Pair as a linked device
|
||||
|
||||
```bash
|
||||
wacli auth
|
||||
```
|
||||
|
||||
`auth` prints a QR code in your terminal. On your phone, open WhatsApp → **Linked devices** → **Link a device**, scan the QR, and approve. As soon as pairing succeeds, `auth` immediately starts the initial sync — keep it running until it idles out or press `Ctrl+C` once it has caught up.
|
||||
|
||||
If the QR does not scan, try `--qr-format text` (numeric fallback) or pair via phone-number code with `--phone +15551234567`.
|
||||
|
||||
> Refresh tokens last as long as the linked device stays linked on your phone. Unlinking from the phone (or `wacli auth logout`) ends the session and requires a fresh QR.
|
||||
|
||||
Verify:
|
||||
|
||||
```bash
|
||||
wacli auth status
|
||||
```
|
||||
|
||||
## 3. Keep the store warm
|
||||
|
||||
```bash
|
||||
wacli sync --follow
|
||||
```
|
||||
|
||||
`sync` never shows a QR; it requires a previously paired session and runs until you stop it. `--once` exits after one idle window; `--follow` reconnects on errors. Both honor `--max-messages` / `--max-db-size` (and the `WACLI_SYNC_MAX_*` env equivalents) so the local store stays bounded.
|
||||
|
||||
See [Sync](sync.md) for refresh-contacts/refresh-groups, `--download-media`, and the idle-exit knobs.
|
||||
|
||||
## 4. Search and read
|
||||
|
||||
```bash
|
||||
# Full-text search (FTS5 when the binary was built with -tags sqlite_fts5; LIKE otherwise)
|
||||
wacli messages search "meeting"
|
||||
|
||||
# Search media-bearing messages
|
||||
wacli messages search "meeting" --has-media
|
||||
|
||||
# List recent messages from a chat, oldest first
|
||||
wacli messages list --chat 1234567890@s.whatsapp.net --asc
|
||||
|
||||
# Show a single message
|
||||
wacli messages show --chat 1234567890@s.whatsapp.net --id <message-id>
|
||||
|
||||
# Show context around a message
|
||||
wacli messages context --chat 1234567890@s.whatsapp.net --id <message-id> --before 5 --after 5
|
||||
```
|
||||
|
||||
`--json` produces a stable envelope; `--full` keeps full IDs in tables. See [Messages](messages.md) for every filter.
|
||||
|
||||
## 5. Send a message
|
||||
|
||||
```bash
|
||||
# Send a text message by phone number, JID, or synced contact/group/chat name
|
||||
wacli send text --to mom --message "hello"
|
||||
|
||||
# Send a quoted reply
|
||||
wacli send text --to 1234567890 --message "replying" --reply-to <message-id>
|
||||
|
||||
# Send a file with a caption
|
||||
wacli send file --to 1234567890 --file ./pic.jpg --caption "hi"
|
||||
|
||||
# Send a native voice note (OGG/Opus)
|
||||
wacli send voice --to 1234567890 --file ./voice.ogg
|
||||
|
||||
# React (omit --reaction for the default thumbs-up; use --reaction "" to clear)
|
||||
wacli send react --to 1234567890 --id <message-id> --reaction "🎉"
|
||||
```
|
||||
|
||||
Recipient resolution and disambiguation (`--pick N`, ambiguous-name prompts), link-preview behavior, and post-send waits are documented in [Send](send.md).
|
||||
|
||||
## 6. Backfill older history (optional, best-effort)
|
||||
|
||||
`sync` only stores what WhatsApp Web pushes. To request older messages for a specific chat from your **primary device** (your phone), use:
|
||||
|
||||
```bash
|
||||
wacli history backfill --chat 1234567890@s.whatsapp.net --requests 10 --count 50
|
||||
```
|
||||
|
||||
The phone must be online. WhatsApp may not return full history. See [History](history.md) for limits and patterns (loop over chats with `jq`, recommended `--count`/`--requests` ceilings).
|
||||
|
||||
## 7. Diagnostics and safety
|
||||
|
||||
```bash
|
||||
wacli doctor
|
||||
wacli doctor --connect
|
||||
|
||||
# Read-only mode for agents / sandboxes
|
||||
wacli --read-only messages search "invoice"
|
||||
WACLI_READONLY=1 wacli send text --to mom --message "hi" # exits with a clear error
|
||||
```
|
||||
|
||||
`doctor` checks the store, schema, FTS5 availability, and (with `--connect`) live connectivity. See [Doctor](doctor.md).
|
||||
|
||||
## 8. Shell completion (optional)
|
||||
|
||||
```bash
|
||||
wacli completion bash >> ~/.bash_completion
|
||||
wacli completion zsh > "${fpath[1]}/_wacli"
|
||||
wacli completion fish > ~/.config/fish/completions/wacli.fish
|
||||
```
|
||||
|
||||
## Where next
|
||||
|
||||
- [Overview](overview.md) — global flags, store model, full command map.
|
||||
- [Send](send.md) — every recipient form, replies, reactions, mentions, link previews.
|
||||
- [Groups](groups.md) — list, refresh, info, rename, participants, invite links.
|
||||
- [Spec](spec.md) — design notes, storage layout, locking model, non-goals.
|
||||
- [Doctor](doctor.md) — self-checks and connectivity probe.
|
||||
Loading…
Reference in New Issue
Block a user