Start

Install

GitHub Edit page

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)

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:

brew update
brew reinstall steipete/tap/wacli

#GitHub releases (raw binaries)

Download the matching archive from the latest release 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:

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

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.

#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 for the layout.
  • Permissions are owner-only (0700 on the directory, 0600 on files). Do not relax these — they protect your WhatsApp session keys.
  • Quickstart — pair, sync, and send your first message.
  • Auth — wacli auth, auth status, auth logout.
  • Sync — bootstrap and follow-mode sync, refresh flags.
  • Doctor — self-checks and connectivity probe.
  • Release — release workflow and artifact expectations.