### Install and Run OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/README.md

Use these commands to install dependencies, start the development server, check types, and build the project.

```bash
pnpm install
```

```bash
pnpm dev
```

```bash
pnpm types:check
```

```bash
pnpm build
```

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

### Install openkakao-cli from Source

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Build and install the openkakao-cli from its source code. This requires Git and Rust to be installed.

```bash
git clone https://github.com/JungHoonGhae/openkakao-cli.git
cd openkakao/openkakao-cli
cargo install --path .
```

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

### Install and Login with OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Install the CLI using Homebrew and log in to your Kakao account. The manual login with save option is recommended for recent KakaoTalk versions.

```bash
# Homebrew
brew tap JungHoonGhae/openkakao
brew install openkakao-cli

# 1. Save auth data
#    Recent KakaoTalk no longer caches the token, so email+password login is recommended (#15)
openkakao-cli login --manual --save
#    (older builds where cache extraction still works: openkakao-cli login --save)
```

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

### Install openkakao-cli via Homebrew

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Use the Homebrew package manager to install the openkakao-cli. Ensure you have the openkakao tap added.

```bash
brew tap JungHoonGhae/openkakao
brew install openkakao-cli
```

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

### JSON Output Examples

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/AGENTS.md

Examples demonstrating the structured JSON output for various commands when the `--json` flag is used. Diagnostic messages are sent to stderr.

```bash
# List chats
openkakao-cli local-chats --json
# Returns: [{"chat_id": 123, "chat_type": 0, "chat_name": "...", ...}]
```

```bash
# Read messages
openkakao-cli local-read 123 --json
# Returns: [{"log_id": 456, "chat_id": 123, "sender_name": "...", "message": "...", ...}]
```

```bash
# Dry-run
openkakao-cli send 123 "hello" --dry-run --json
# Returns: {"dry_run": true, "action": "send", "chat_id": 123, "message": "..."}
```

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

### Verify OpenKakao CLI Installation

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/installation.mdx

Check the installed version of the openkakao-cli to confirm successful installation.

```bash
openkakao-cli --version
```

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

### Example GETCONF Request Packet

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/packets.mdx

Illustrates the byte-level breakdown of a GETCONF request, showing the header fields and the corresponding BSON body content. This example helps visualize packet construction and interpretation.

```text
Header (22 bytes):
  packet_id:   01 00 00 00      (1)
  status_code: 00 00            (0)
  method:      47 45 54 43 4F 4E 46 00 00 00 00  ("GETCONF\0\0\0\0")
  body_type:   00               (0)
  body_length: 1A 00 00 00      (26)

Body (26 bytes):
  BSON document: {"os": "mac", "model": "mac"}
```

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

### Diagnostic Commands

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/AGENTS.md

Run diagnostic commands to check the installation, credentials, local database access, and authentication status.

```bash
openkakao-cli doctor --json        # Check installation, credentials, local DB access
```

```bash
openkakao-cli auth-status --json   # Check auth recovery state
```

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

### Example TOML Configuration

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/configuration.mdx

This TOML file demonstrates how to configure various aspects of the OpenKakao CLI, including mode, send, watch, auth, and safety settings. Use this for unattended services to set stable policies.

```toml
[mode]
unattended = true

[send]
allow_non_interactive = true
default_prefix = true

[watch]
allow_side_effects = true
default_max_reconnect = 10

[auth]
prefer_relogin = true
auto_renew = true
password_cmd = "doppler secrets get KAKAO_PASSWORD -p openkakao -c dev --plain"

[safety]
min_unattended_send_interval_secs = 10
min_hook_interval_secs = 2
min_webhook_interval_secs = 2
hook_timeout_secs = 20
webhook_timeout_secs = 10
allow_insecure_webhooks = false
allow_loco_write = false

```

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

### Connect to Local Hooks with Watch Command

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Connect the `watch` command to local command-line hooks or webhooks for automated processing of real-time events. This example pipes the JSON output to a file using `jq`.

```bash
# Connect to local hooks or webhooks
openkakao-cli --unattended --allow-watch-side-effects watch \
  --hook-cmd 'jq . > /tmp/openkakao-event.json'
```

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

### Watch Command with Hook Command

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

This example demonstrates how to use the `openkakao-cli watch` command with the `--hook-cmd` option to process matched message events. The output of the hook command is piped to `jq` and then redirected to a JSON file.

```bash
openkakao-cli watch \
  --unattended \
  --allow-watch-side-effects \
  --hook-cmd 'jq . > /tmp/openkakao-event.json' \
  --hook-chat-id 900000000000001 \
  --hook-type 1
```

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

### Watch All Chats

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/watch-patterns.mdx

Use this command to start watching all incoming messages in all chats.

```bash
openkakao-cli watch
```

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

### Watch Command with Webhook

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

This example shows how to configure `openkakao-cli watch` to send event data to a webhook URL using the `--webhook-url` option. It also includes setting a custom header and a secret for webhook signing.

```bash
openkakao-cli watch \
  --unattended \
  --allow-watch-side-effects \
  --webhook-url https://hooks.example.com/openkakao \
  --webhook-header 'X-OpenKakao-Source: laptop' \
  --webhook-signing-secret 'super-secret' \
  --hook-keyword urgent
```

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

### Send Photo Command Example

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

An alias for send-file, this command sends a photo. The -y flag skips the confirmation prompt.

```bash
openkakao-cli --unattended --allow-non-interactive-send send-photo <chat_id> photo.jpg -y
```

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

### Preview deleting a message with JSON output

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

Shows how to use the --dry-run and --json flags together for the delete command to preview the action and get JSON output.

```bash
openkakao-cli delete 123 456 --dry-run --json
```

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

### Get Profile Hints from Local Graph

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/friends.mdx

Provides hints for profile probing, such as candidate chat IDs and GETMEM tokens, by analyzing the local LOCO graph. Use `--json` for structured output. The `--probe-syncmainpf` flag is used for specific probing scenarios.

```bash
openkakao-cli profile-hints --local-graph --json
```

```bash
openkakao-cli profile-hints --local-graph --user-id <user_id> --probe-syncmainpf --json
```

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

### Watch Command with Combined Options

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/watch-patterns.mdx

Use this command to start watching a chat with multiple configuration options. It includes unattended mode, allowing watch side effects, and specifies chat ID, read receipts, media downloads, and hook configurations.

```bash
openkakao-cli --unattended --allow-watch-side-effects watch \
  --chat-id <chat_id> \
  --read-receipt \
  --download-media \
  --download-dir ./media \
  --hook-cmd 'jq . > /tmp/openkakao-event.json' \
  --hook-type 1 \
  --max-reconnect 10
```

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

### React message JSON output

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

Example of the JSON output when the --json flag is used with the react command.

```json
{"chat_id": 900000000000001, "log_id": 123456789, "reaction_type": 1, "status": "reacted"}
```

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

### Get Chat Room Information

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Retrieves detailed information about a chat room, returning the raw LOCO CHATONROOM response.

```bash
openkakao-cli chatinfo <chat_id>
```

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

### Webhook Signature Verification

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

This example illustrates how to verify the signature of an incoming webhook request from openkakao-cli. It uses `openssl` to compute the SHA256 HMAC of the timestamp and payload, comparing it against the received signature.

```bash
BODY_FILE=/tmp/openkakao-body.json
printf '%s.%s' "$HTTP_X_OPENKAKAO_TIMESTAMP" "$(cat "$BODY_FILE")" \
  | openssl dgst -sha256 -hmac 'super-secret'
```

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

### Load OpenKakao Watch Agent

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/examples/launchd/README.md

Bootstrap the OpenKakao watch agent using launchctl. Ensure the .plist file is in the correct directory.

```bash
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.openkakao.watch.plist
```

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

### Step 1: Booking (GETCONF)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/connection.mdx

Initiates a TLS connection to the booking server to retrieve server configurations, including checkin host and port candidates.

```APIDOC
## Step 1: Booking (GETCONF)

TLS connection to `booking-loco.kakao.com:443`.

### Request
```json
{
  "GETCONF": {
    "os": "mac",
    "model": "mac"
  }
}
```

### Response
Server configuration including checkin host list and port candidates.
```

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

### GETMEM — Get Members

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/commands.mdx

Retrieves the members of a chat room.

```APIDOC
## GETMEM — Get Members

### Description
Retrieves the members of a chat room.

### Request Body
```json
{
  "chatId": 900000000000001
}
```
```

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

### Show Account Settings

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/profile.mdx

Displays your current account settings.

```bash
openkakao-cli settings [--json]
```

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

### Get Chat Info (CHATONROOM)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/commands.mdx

Retrieves information about a specific chat room using its 'chatId'.

```json
{
  "chatId": 900000000000001
}
```

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

### Step 3: Login (LOGINLIST)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/connection.mdx

Connects to the assigned LOCO server using RSA handshake and AES-GCM for authentication. This step also handles fetching recent messages if `chatIds` and `maxIds` are provided.

```APIDOC
## Step 3: Login (LOGINLIST)

Connect to the assigned LOCO server with RSA handshake + AES-GCM, then authenticate:

### Request
```json
{
  "LOGINLIST": {
    "token": "<access_token>",
    "chatIds": [],
    "maxIds": [],
    "lastTokenId": 0,
    "lbk": 0,
    "bg": false,
    "os": "mac",
    "ntype": 0,
    "appVer": "3.7.0",
    "MCCMNC": "999",
    "lang": "ko",
    "dtype": 2,
    "duuid": "<device_uuid>",
    "prtVer": "1"
  }
}
```

When `chatIds` and `maxIds` are populated, the server returns recent messages for those chats in the response. This is used by the `read` command (v0.7.1+) to bootstrap message history directly from the login handshake, avoiding an extra SYNCMSG round-trip for the initial batch.

### Response
Status 0 with userId, chat room list, and (when requested) per-chat `chatDatas` containing `chatLog` message arrays.
```

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

### Build Open-Kakao CLI Project

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Navigate to the project directory and build the release version of the Open-Kakao CLI using Cargo. This command is used during development.

```bash
cd openkakao-cli
cargo build --release
```

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

### Delete message JSON output

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

Example of the JSON output when the --json flag is used with the delete command.

```json
{"chat_id": 900000000000001, "log_id": 123456789, "status": "deleted"}
```

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

### OpenKakao CLI Working Model

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/index.mdx

This diagram illustrates the OpenKakao CLI's interaction with the KakaoTalk macOS app, various Kakao servers (REST and LOCO), and local tools. It highlights the use of REST for cache-backed reads and LOCO for real-time chat features.

```mermaid
flowchart LR
    A[KakaoTalk macOS app] -->|Cache and app state| O[openkakao-cli]
    O -->|REST calls| K[katalk.kakao.com]
    O -->|REST calls| P[talk-pilsner.kakao.com]
    O -->|LOCO TCP plus BSON| L[booking and ticket and LOCO servers]
    O -->|JSON output| T[Shell scripts, jq, sqlite, LLM tools]
```

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

### OpenKakao CLI Usage

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/overview.mdx

The basic structure for using the openkakao-cli. It accepts global options followed by a specific command.

```bash
openkakao-cli [OPTIONS] <COMMAND>
```

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

### Export Recent Chat Messages

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/common-recipes.mdx

Exports a specified number of recent messages from a chat to a JSON file. This is the safest starting point for analysis workflows because it is read-only.

```bash
openkakao-cli read <chat_id> -n 200 --json > messages.json
```

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

### Login and Save Credentials

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/auth.mdx

Extracts credentials from a running KakaoTalk app and saves them to a local file for future use. This is useful for initial setup or when migrating to a new environment.

```bash
openkakao-cli login --save
```

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

### Generate Shell Completions

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/installation.mdx

Set up shell completions for zsh, fish, and bash to improve command-line usability.

```bash
# zsh
openkakao-cli completions zsh >> ~/.zfunc/_openkakao-cli

# fish
openkakao-cli completions fish > ~/.config/fish/completions/openkakao-cli.fish

# bash
openkakao-cli completions bash >> ~/.bash_completion
```

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

### Manually Create credentials.json

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/troubleshooting.mdx

Manually create the credentials.json file if you have an existing token. Ensure all fields are correctly populated.

```json
{
  "oauth_token": "<Authorization header value>",
  "user_id": 1234567890,
  "device_uuid": "<suffix after the first '-' of the token>",
  "app_version": "3.7.0",
  "user_agent": "",
  "a_header": ""
}
```

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

### Filter LOCO Messages by Date

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/docs/IMPROVEMENT_PLAN.md

Retrieve messages from a specific chat within a date range using the `loco-read` command with the `--all --since` flags, followed by the desired start date.

```bash
openkakao-cli loco-read <chat_id> --all --since 2024-06-01
```

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

### Recommended Flow for Inspecting UI Changes

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/diagnostics.mdx

A recommended workflow to inspect changes when opening profile or multi-profile UIs. Capture a baseline app state, interact with the UI in KakaoTalk, then compare the new state against the baseline.

```bash
openkakao-cli profile-hints --app-state --json > /tmp/profile-before.json
# open the target profile or multi-profile UI in KakaoTalk
openkakao-cli profile-hints --app-state --app-state-diff /tmp/profile-before.json --json
```

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

### Download Media to a Custom Directory

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/media.mdx

Specify a custom output directory for downloaded media using the -o or --output-dir flag.

```bash
openkakao-cli download 900000000000001 9000000000000000001 -o ./media
```

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

### Get User Profile within a Chat

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Retrieves a user's profile within a specific chat context using LOCO's `GETMEM`. This provides member metadata aligned with `members --full`.

```bash
openkakao-cli profile <user_id> --chat-id <chat_id>
```

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

### Capture Application State for Diffing

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Capture the current application state into a JSON file. This is typically the first step before performing an action to later compare the state.

```bash
openkakao-cli profile-hints --app-state --json > /tmp/profile-before.json
```

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

### Preview sending a message

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

Demonstrates the --dry-run flag for the send command, showing the would-be output without executing the action.

```bash
openkakao-cli send 123 "hello" --dry-run
```

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

### List Multi-Profiles

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/profile.mdx

Lists all available multi-profiles associated with your account.

```bash
openkakao-cli profiles [--json]
```

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

### Step 2: Checkin

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/connection.mdx

Establishes a legacy encrypted connection using RSA handshake and AES-GCM to a checkin server. The client attempts multiple host:port combinations provided in the booking response.

```APIDOC
## Step 2: Checkin

Legacy encrypted connection (RSA handshake + AES-GCM) to a checkin server.

The client tries multiple host:port combinations from the booking response until one succeeds:
- `ticket-loco.kakao.com:443` (TLS — may fail)
- `ticket-loco.kakao.com:995` (Legacy encrypted)
- `ticket-loco.kakao.com:10009` (Legacy encrypted)

### Request
```json
{
  "CHECKIN": {
    "userId": 100000001,
    "os": "mac",
    "ntype": 0,
    "appVer": "3.7.0",
    "MCCMNC": "999",
    "lang": "ko",
    "countryISO": "KR",
    "useSub": true
  }
}
```

### Response
Assigned LOCO server IP and port.
```

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

### Send Message Without Prefix

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

To send a message without the default '🤖 [Sent via openkakao]' prefix, use the global --no-prefix flag. This example also demonstrates unattended sending with confirmation skipped.

```bash
openkakao-cli --unattended --allow-non-interactive-send --no-prefix send <chat_id> "raw message" -y
```

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

### Get Chat Room Information

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Retrieves detailed information about a specific chat room, including metadata, settings, and member count. It returns the raw LOCO CHATONROOM response. Using chat ID '0' is a special case to find or create a MemoChat.

```APIDOC
## chatinfo

Get detailed information about a chat room.

```bash
openkakao-cli chatinfo <chat_id>
```

### Parameters

- `<chat_id>`: The ID of the chat room. Use `0` to find or create a MemoChat.
```

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

### Inspect App State Snapshots

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/diagnostics.mdx

Capture file metadata, preferences, and Cache.db information from the KakaoTalk container. Useful for reverse-engineering app states.

```bash
openkakao-cli profile-hints --app-state --json
```

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

### Upgrade OpenKakao CLI with Homebrew

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/installation.mdx

Update Homebrew and upgrade the openkakao-cli package to the latest version.

```bash
brew update && brew upgrade openkakao-cli
```

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

### Run `doctor` Command for Environment Health Check

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/docs/IMPROVEMENT_PLAN.md

Execute the `doctor` command to diagnose the health of your KakaoTalk environment. This command checks for installed versions, process status, database freshness, token validity, connectivity, and credential file status without making any changes.

```bash
openkakao-cli doctor
```

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

### settings

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/profile.mdx

Display your account settings.

```APIDOC
## settings

### Description
Show account settings.

### Command
```bash
openkakao-cli settings [--json]
```
```

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

### Get User Profile within a Chat

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Retrieves a user's profile information within the context of a specific chat room using LOCO's GETMEM. This command can also resolve profiles from the local LOCO graph if the chat ID is not known or if falling back from the REST path.

```APIDOC
## profile (chat-scoped LOCO)

`profile` can point at a specific chat and reuse LOCO `GETMEM`.

```bash
openkakao-cli profile <user_id> --chat-id <chat_id>
```

### Parameters

- `<user_id>`: The ID of the user whose profile to retrieve.
- `--chat-id <chat_id>`: The ID of the chat room to scope the profile lookup.

If you do not know the right chat, you can also resolve from the local LOCO graph:

```bash
openkakao-cli profile <user_id> --local
```

This scans known chats and merges `GETMEM` results into a partial graph. It is slower than `--chat-id`, but it can still resolve users that have already appeared somewhere in your LOCO-visible chat set.

When you run plain `profile <user_id>`, OpenKakao still tries the REST friend profile path first. If that fails, it automatically falls back to the local LOCO graph before giving up.
```

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

### Booking Request (GETCONF)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/connection.mdx

Initiates a TLS connection to the booking server to retrieve configuration details. This request specifies the client's operating system and model.

```json
{
  "GETCONF": {
    "os": "mac",
    "model": "mac"
  }
}
```

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

### Inspect App State for Profile Changes

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/friends.mdx

Captures the application's state for profile-related changes on disk, allowing for before-and-after comparisons. The output is saved to a temporary file for diffing.

```bash
openkakao-cli profile-hints --app-state --json > /tmp/profile-before.json
```

```bash
openkakao-cli profile-hints --app-state --app-state-diff /tmp/profile-before.json --json
```

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

### Add OpenKakao CLI Skill to Claude Code

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Integrate the openkakao-cli functionality into Claude Code by adding the skill using npx.

```bash
npx skills add JungHoonGhae/skills@openkakao-cli
```

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

### Authenticate with OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/quickstart.mdx

Log in and save your credentials for future use. This command requires KakaoTalk to be running and already logged in.

```bash
openkakao-cli login --save
openkakao-cli auth
```

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

### List Chats with OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/quickstart.mdx

Retrieve a list of your available chats. This is a preliminary step before reading specific chat content.

```bash
openkakao-cli chats
```

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

### Set Up Keyword Alert

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/common-recipes.mdx

Monitors chat messages for specific keywords and displays a desktop notification when a match is found. Redirects stderr to /dev/null to suppress potential errors from the watch command.

```bash
openkakao-cli watch 2>/dev/null | while read -r line; do
  if echo "$line" | grep -qi "urgent\|emergency"; then
    osascript -e "display notification \"$line\" with title \"KakaoTalk Alert\""
  fi
done
```

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

### Basic Watch Command Usage

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

This is the basic syntax for running the watch command. It can be extended with various options to filter and process messages.

```bash
openkakao-cli watch [OPTIONS]
```

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

### Auto-Download Media in Watch Mode

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/media.mdx

Enable automatic media downloading as new messages arrive by running the watch command with the --download-media and --download-dir flags.

```bash
openkakao-cli watch --download-media --download-dir ./media
```

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

### Local Summarization with OpenKakao CLI and LLM

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/llm-agent-workflows.mdx

Reads recent messages from a chat, formats them for an LLM, and pipes the output to a local summarization command. Use this for trusted local LLM environments.

```bash
openkakao-cli read <chat_id> -n 50 --json | \
  jq -r '.[] | "\(.author): \(.message)"' | \
  llm "Summarize this conversation in 3 bullet points"
```

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

### Compare App State Snapshots

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/diagnostics.mdx

Compare the current app state snapshot against a previous baseline JSON output. This helps identify changes in file metadata, preferences, and Cache.db.

```bash
openkakao-cli profile-hints --app-state --app-state-diff /tmp/profile-before.json --json
```

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

### Send Videos

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/sending-messages.mdx

Send videos to a chat. Supported formats are MP4, MOV, WebM.

```bash
openkakao-cli send-file <chat_id> video.mp4 -y
```

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

### List Friends with Options

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/friends.mdx

Lists friends with various filtering and output options. Use `--json` for machine-readable output.

```bash
openkakao-cli friends [OPTIONS]
```

```bash
openkakao-cli friends -s "John"
```

```bash
openkakao-cli friends --json | jq '.[].nickname'
```

```bash
openkakao-cli friends --local -s "Alice"
```

```bash
openkakao-cli friends --local --hidden
```

```bash
openkakao-cli friends --local --chat-id 900000000000003
```

```bash
openkakao-cli friends --local --user-id 100000003 --json
```

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

### Watch Command with Webhook Headers and Signing

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

Configure custom HTTP headers and enable HMAC-SHA256 signing for webhook payloads to secure the communication.

```bash
openkakao-cli watch --webhook-url "http://localhost:3000/event" --webhook-header "Authorization: Bearer YOUR_TOKEN" --webhook-signing-secret "YOUR_SECRET_KEY"
```

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

### Show Notification Keywords

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/profile.mdx

Retrieves the list of notification keywords configured for your account.

```bash
openkakao-cli keywords [--json]
```

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

### Watch Command with Media Downloads

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

Automatically download media attachments from incoming messages to a specified directory.

```bash
openkakao-cli watch --download-media --download-dir "./media_files"
```

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

### Structured Output for Agents with OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Obtain command output in JSON format for easier parsing by agents or scripts. This is useful for integrating CLI data into automated workflows.

```bash
# Structured output
openkakao-cli --json chats
openkakao-cli --json read <chat_id> -n 20
```

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

### profiles

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/profile.mdx

List all available multi-profiles associated with your account.

```APIDOC
## profiles

### Description
List multi-profiles.

### Command
```bash
openkakao-cli profiles [--json]
```
```

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

### Send Files

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/sending-messages.mdx

Send any file type to a chat. The CLI detects media types automatically and falls back to generic file upload.

```bash
openkakao-cli send-file <chat_id> document.pdf -y
```

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

### Preview Actions Without Execution

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/AGENTS.md

Simulate write operations like sending, deleting, or editing messages using the `--dry-run` flag. This is a safe way to test commands before actual execution.

```bash
openkakao-cli send 123 "message" --dry-run --json
```

```bash
openkakao-cli delete 123 456 --dry-run --json
```

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

### Watch and Download Media

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/watch-patterns.mdx

Automatically download media attachments (photos, videos, audio, files) as they arrive.

```bash
openkakao-cli watch --download-media
```

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

### Relogin or Renew Credentials

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/authentication.mdx

Commands to re-authenticate or renew access tokens. `--fresh-xvc` forces a fresh X-VC header reconstruction for relogin. `renew` uses the refresh token to request a new access token.

```bash
openkakao-cli relogin --fresh-xvc
```

```bash
openkakao-cli renew
```

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

### Run Diagnostics

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/local-db.mdx

Runs diagnostics to check if the local database is accessible. The output includes information about UUID extraction, user ID, file existence, and decryption status.

```bash
openkakao-cli doctor --json
```

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

### Risky Write Commands (Opt-in Required)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/AGENTS.md

Execute write operations like send, delete, edit, and react. These commands are disabled by default and require setting `allow_loco_write = true` in the configuration file.

```bash
openkakao-cli send <chat_id> "message" -y --json
```

```bash
openkakao-cli send --me "test" -y --json
```

```bash
openkakao-cli delete <chat_id> <log_id> -y --json
```

```bash
openkakao-cli edit <chat_id> <log_id> "new" -y --json
```

```bash
openkakao-cli react <chat_id> <log_id> --json
```

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

### Read Messages (Default LOCO)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/message.mdx

Fetches messages from a chat room using the default LOCO path for reliable history. Use '--all' to fetch all available messages and '--json' to output in JSON format.

```bash
openkakao-cli read <chat_id> --all --json > history.json
```

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

### Authenticate and Sync (LOGINLIST)

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/commands.mdx

This command is sent during the login process to authenticate and sync recent messages. It can specify 'chatIds' and 'maxIds' to request message history.

```json
{
  "chatIds": [],
  "maxIds": []
}
```

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

### Password from Doppler

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/configuration.mdx

Configures unattended relogin by pulling the Kakao password from Doppler secrets. The command is executed only when relogin requires a password.

```toml
[auth]
prefer_relogin = true
auto_renew = true
password_cmd = "doppler secrets get KAKAO_PASSWORD -p openkakao -c dev --plain"
```

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

### Unattended Operation Configuration

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/AGENTS.md

Configure openkakao-cli for fully non-interactive operation using command-line flags or by setting parameters in `~/.config/openkakao/config.toml`.

```bash
openkakao-cli --unattended --allow-non-interactive-send send <chat_id> "msg" -y --json
```

```toml
[mode]
unattended = true

[send]
allow_non_interactive = true

[safety]
allow_loco_write = true
min_unattended_send_interval_secs = 10
```

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

### Monitor OpenKakao Watch Agent

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/examples/launchd/README.md

Check the status of the OpenKakao watch agent and tail its error log. Also, verify authentication and system health.

```bash
launchctl print gui/$(id -u)/com.openkakao.watch
```

```bash
tail -f ~/Library/Logs/openkakao/watch.stderr.log
```

```bash
openkakao-cli auth-status
```

```bash
openkakao-cli doctor --loco
```

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

### Watch with Raw BSON Body

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/automation/watch-patterns.mdx

Display the raw BSON body of incoming messages for detailed inspection.

```bash
openkakao-cli watch --raw
```

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

### Send File Command Syntax

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/send.mdx

Use this command to send various file types via LOCO SHIP+POST. The media type is auto-detected from file magic bytes.

```bash
openkakao-cli send-file <chat_id> <file> [OPTIONS]
```

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

### List All Chat Rooms

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Includes low-signal or mostly empty rooms when listing chats.

```bash
openkakao-cli chats --all
```

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

### Watch Command with Webhook Delivery

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

POST matched message events to a specified webhook URL. Use this when you want message events to leave the machine.

```bash
openkakao-cli watch --webhook-url "http://localhost:3000/event"
```

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

### List and Read Chats with OpenKakao CLI

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

List all available chats and read recent messages from a specific chat ID. These commands interact directly with the KakaoTalk server.

```bash
# 2. List chats
openkakao-cli chats

# 3. Read messages
openkakao-cli read <chat_id> -n 20
```

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

### Capture push packets in idle listen mode

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/overview/changelog.mdx

Extends the timeout for idle listen mode to 10 seconds, specifically for capturing push packets.

```bash
probe --capture-pushes
```

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

### Watch Real-time Events with JSON Output

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/README.en.md

Stream real-time events from KakaoTalk in JSON format. This allows for monitoring and reacting to events as they happen.

```bash
# Real-time event stream
openkakao-cli watch --json
```

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

### Download Media from a Specific Message

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/media.mdx

Use this command to download media from a particular message identified by its chat ID and log ID.

```bash
openkakao-cli download 900000000000001 9000000000000000001
```

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

### Watch Command with Hook Fail Fast Option

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/watch.mdx

Configure the watch command to exit immediately if a hook command fails.

```bash
openkakao-cli watch --hook-cmd "./my_script.sh" --hook-fail-fast
```

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

### Manual Login for macOS Cache Issues

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/getting-started/troubleshooting.mdx

Use this command when `login --save` fails due to KakaoTalk macOS app cache changes. It bypasses the cache by using email and password authentication.

```bash
openkakao-cli login --manual --save
```

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

### List Recent Chats

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/local-db.mdx

Lists recent chat rooms from the local database. Use the `--json` flag for machine-readable output.

```bash
openkakao-cli local-chats
```

```bash
openkakao-cli local-chats --json
```

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

### Find or Create MemoChat

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/cli/chat.mdx

Uses `chatinfo` with chat ID `0` to find an existing MemoChat or create a new one. This is the reliable way to access your private chat-with-yourself room.

```bash
openkakao-cli chatinfo 0
```

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

### Checkin Request

Source: https://github.com/junghoonghae/openkakao-cli/blob/main/website/content/docs/protocol/connection.mdx

Establishes a legacy encrypted connection to a check-in server using details obtained from the booking response. This request includes user and device information for authentication.

```json
{
  "CHECKIN": {
    "userId": 100000001,
    "os": "mac",
    "ntype": 0,
    "appVer": "3.7.0",
    "MCCMNC": "999",
    "lang": "ko",
    "countryISO": "KR",
    "useSub": true
  }
}
```