From b974645fdb4fd07f8f8dbc795aa250810c835c46 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Tue, 5 May 2026 08:24:28 +0100 Subject: [PATCH] docs: add hosted documentation pages --- README.md | 4 +- docs/CNAME | 1 + docs/index.md | 42 +++++++++++++++ docs/install.md | 83 +++++++++++++++++++++++++++++ docs/quickstart.md | 126 +++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 255 insertions(+), 1 deletion(-) create mode 100644 docs/CNAME create mode 100644 docs/index.md create mode 100644 docs/install.md create mode 100644 docs/quickstart.md diff --git a/README.md b/README.md index 1ffb466..3ba2c8e 100644 --- a/README.md +++ b/README.md @@ -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: . + - [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. diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 0000000..3d3245e --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +wacli.sh diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f6f9cae --- /dev/null +++ b/docs/index.md @@ -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). diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..4625c5e --- /dev/null +++ b/docs/install.md @@ -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. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..9e66913 --- /dev/null +++ b/docs/quickstart.md @@ -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 + +# Show context around a message +wacli messages context --chat 1234567890@s.whatsapp.net --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 + +# 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 --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.