whatsapp-cli: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

whatsapp-cli provides WhatsApp access from your terminal. Machine-readable output (JSON, JSONL, CSV, TSV, human tables).

Development Commands

make build                          # Build binary (requires CGO)
make run CMD="chats --limit 5"      # Run CLI command
make test                           # Run all tests
make lint                           # Check linting
make fmt                            # Format code
make can-release                    # Full CI (lint + test)

Architecture

cmd/whatsapp/main.go                # Entry point

internal/
├── cli/                            # Cobra commands, config, output, temporal parsing
├── store/                          # SQLite + FTS5 database, models (Chat, Message, Contact)
└── whatsapp/                       # WhatsApp client (connection, sync, messaging, media)

Requires Go 1.25+, CGO enabled, SQLite with FTS5. FFmpeg optional for audio.

Key Pattern

Commands use shared helpers for database and client setup:

// Database-only (chats, messages, search)
func runChats(cmd *cobra.Command, args []string) error {
    return WithDB(func(db *store.DB) error {
        chats, err := db.ListChats(store.ListChatsOptions{...})
        if err != nil {
            return err
        }
        return Output(chats)  // Auto-serialized based on --format
    })
}

// With WhatsApp connection (send, sync)
func runSend(cmd *cobra.Command, args []string) error {
    return WithConnection(func(db *store.DB, client *whatsapp.Client) error {
        result, err := client.SendTextMessage(jid, message)
        if err != nil {
            return err
        }
        return Output(result)
    })
}

Testing

Tests use go test -tags sqlite_fts5. Manual testing: ./dist/whatsapp doctor and ./dist/whatsapp auth status.

Data Units

All timestamps ISO8601 UTC. JIDs: [email protected] (individual), [email protected] (group).