Command Reference

talkbridge <command> [options]. Commands that require authentication need a key registered first via setup / login.

Option notation: --channel key of the target channel · --to (=--user) target customer key · --channel is required for most commands.

The value for --channel is the Brand Key (channel key). Find it in the "Integration keys" card in Developer mode of TalkBridge Center, or pick it from the consultable channels listed by talkbridge whoami. It is the same value as brandKey in the API.

• There is one key per channel. If a brand has KakaoTalk, LINE and Naver TalkTalk channels connected, it has three keys.
• --channel is available from CLI v1.2.0. The previous name --brand still works, so use --brand with CLI v1.1 or earlier.

Global option --json — add it to any command to get a single-line JSON instead of human-readable text (for programs; see JSON output).

All commands

Command	Action	Main options
setup [<key>]	Verify and store a key / TUI if no argument. Full option list: setup --help (no side effects)	--endpoint, sink, CRM, and AI flags, --dry-run
login	Obtain and store a key via web OAuth pairing	--console, --endpoint
whoami	My name, permissions, endpoint, consultable channels (grouped by brand)	—
env	Show this executable's channel, target server, config path, and binary path (no authentication needed)	--json → binaryPath, launcherPath
history	Consultation history (in progress/completed, convId)	--channel
rooms	List consultation rooms / messages in a specific room	--channel (required), --user, --max N
send	Send text/rich/attachment messages	--channel, --to, --text, --rich-json <file>, --file <path> (repeatable)
delete	Delete a sent message — within 24 hours of sending	--channel, --to, --serial <serial number> or --text <body> [--within <seconds>]
profile	View sender profile	--channel (required)
webhook-domain	Get/set inbound domain	get/set, --channel, --url
chat	Toggle chat feature	activate/deactivate, --channel
schedule	Get/set consultation hours	get/set, --channel, --json <file>
block / unblock	Block / unblock a user	--channel, --to
end-with-bot	End + switch to bot (handoff)	--channel, --to, --event
personal-info	Request personal-info consent (Kakao) — the result arrives as a webhook personal_info	--channel, --to
sysmsg	View system messages	--channel (required)
upload	Upload multimedia	image/file/audio/video, --channel, --file
gateway	Outbound Gateway daemon	start/stop/restart/status → Gateway
knowledge	Consultation knowledge ontology (graph RAG) → below	status/install/build/search/query/view
model	List/select AI model	list / set <id>
chatbot	Interactive TUI for AI consultation assistance	(requires setup and model first)

Differences between the CLI and REST

• Attachments are sent with CLI send --file (delivered to the customer directly) or REST POST /api/agent/send/attachments. upload only returns a URL.
• End with a greeting only (POST /api/agent/end) exists in REST only — the CLI offers end-with-bot (end + hand off to bot).
• The three settings changes (webhook-domain set, chat activate|deactivate, schedule set) require an Admin-scope key. A BrandWrite key can only read them (403 FORBIDDEN).

Frequently used examples

My info · history

talkbridge whoami
talkbridge history --channel mychannel
talkbridge rooms --channel mychannel --user Ab3d_x9Kq2Lm --max 20

whoami lists the channels this key can consult on, grouped by brand. The middle column is the key you pass to --channel. The CLI prints its labels in Korean:

상담 가능 채널 (3):   ← send·rooms 등의 --channel <채널키>
  My Brand (브랜드 mybrand-1a2b3c)
    - 카카오  mychannel               KakaoTalk channel
    - LINE    ch-5d6e7f               LINE official account
    - 네이버  ch-8a9b0c               Naver TalkTalk

Send (text)

talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --text "Hello"

Send (rich)

Create a rich envelope JSON file and pass it. chat_bubble_type is required; the sender identification fields are filled in by the server.

talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --rich-json rich.json

The envelope schema and three examples are in Outbound API → Rich envelope schema.

Send (attachments)

Sends images and files straight to the customer. The server uploads them to Kakao and assembles the bubbles (image = rich IMAGE, file = plain FILE). If you pass --text as well, it goes into the first bubble.

talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --file ./photo.png --file ./manual.pdf --text "Here is the material you requested"

Cancel a send (delete)

Delete by the serial number shown in the send result, or if you don't know the number, find the recent send by its body text and delete it.

talkbridge delete --channel mychannel --to Ab3d_x9Kq2Lm --serial 1234567890
talkbridge delete --channel mychannel --to Ab3d_x9Kq2Lm --text "Hello" --within 600

• Deletion is only possible within 24 hours of sending. A "This message has been deleted" notice is shown in the customer's chat room.
• Deleting does not restore the consultation count.
• Personal-data consent and KakaoTalk verification bubbles cannot be deleted.
• --text only finds a match when the body matches exactly. If it can't be found, increase --within (seconds, 10–86400) or specify --serial directly.

Channel settings

# Inbound domain
talkbridge webhook-domain set --channel mychannel --url https://hook.example.com
# Toggle chat feature
talkbridge chat activate --channel mychannel
# Consultation hours (from a JSON file)
talkbridge schedule set --channel mychannel --json schedule.json

Customer management · handoff

talkbridge block   --channel mychannel --to Ab3d_x9Kq2Lm
talkbridge unblock --channel mychannel --to Ab3d_x9Kq2Lm
talkbridge end-with-bot --channel mychannel --to Ab3d_x9Kq2Lm --event welcome

Upload

talkbridge upload image --channel mychannel --file photo.jpg
talkbridge upload file  --channel mychannel --file manual.pdf

JSON output (--json)

Add --json to any command to get a single-line JSON on stdout instead of text. Diagnostics go to stderr, and errors come back as {"ok":false,"error":"…","code":"…"}. Field names are the same as the REST responses (userKey, lastSeq, timestampUnixMs, kind, text, …), so an integration that starts with the CLI keeps the same model when it moves to REST.

talkbridge rooms --channel mychannel --json | jq '.[0].userKey'
talkbridge rooms --channel mychannel --user Ab3d_x9Kq2Lm --json      # [{seq,userKey,sessionId,kind,text,timestampUnixMs}]
talkbridge history --channel mychannel --json                          # [{brand,conversations:[{convId,userKey,ended,count,last,lastActivity,…}]}]
talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --text "Hello" --json   # {"ok":true,"brandKey":…,"userKey":…,"serial":"bw-…"}
talkbridge whoami --json · env --json · gateway status --json · knowledge status --json

Timestamps in text mode now include the year (2026-09-08 10:28), so existing code that parsed the text no longer has to guess across year boundaries.

Calling the CLI from a program

When you spawn the CLI from a script or server, run the binary directly. On Windows, spawning the .cmd shim that npm creates is refused by recent Node versions (18.20+/20.12+, EINVAL), and working around it with shell: true lets " & % ^ in consultation messages be eaten by the cmd parser — garbled text or injection.

1. Read the paths with talkbridge env --json — no discovery logic needed.

   { "binaryPath": "…/@blumn-ai/talkbridge-cli-win32-x64/talkbridge.exe", "binaryArgs": [], "launcherPath": "…/@blumn-ai/talkbridge-cli/bin/talkbridge.js", … }

2. Spawn binaryPath with an argument array (no shell). If launcherPath is present you can also run that JS with process.execPath.

const { execFileSync, spawn } = require('node:child_process');
const env = JSON.parse(execFileSync('talkbridge', ['env', '--json'], { shell: process.platform === 'win32' }));
// From here on, spawn the binary directly without a shell — any character in the message is passed through as-is
const child = spawn(env.binaryPath, [...env.binaryArgs, 'send', '--channel', 'mychannel', '--to', userKey, '--text', text, '--json'],
  { stdio: ['ignore', 'pipe', 'pipe'] });

• When you kill on timeout, kill the process tree (Windows taskkill /T /F /PID). Killing only the launcher (node) can leave the binary alive holding the graph DB lock. If you spawned the binary directly, ending that one process is enough.
• The launcher (launcherPath) forwards SIGINT/SIGTERM/SIGHUP to the child.

Consultation knowledge ontology (knowledge)

Builds and searches a customer → inquiry → response graph (LadybugDB, embedded locally) from consultations. AI is optional — it is only needed for entity (keyword) extraction and natural-language search; install, build, and Cypher search work without it.

Command	Action
knowledge install	Install the LadybugDB lib + enable + schema (no AI needed)
knowledge build [--channel <key>]	Bulk-load past consultations. Inquiry.ts/Response.ts hold the original message time; the load time is loadedAt
knowledge search --cypher "<Cypher>"	Read-only Cypher (MATCH/RETURN). Prints every column; --json gives {"columns":[…],"types":[…],"rows":[[…]]} with numbers and booleans preserved
knowledge search "<natural language>"	AI keyword extraction → node matching (without AI it points you to --cypher)
knowledge query [--write] "<Cypher>[; …]"	Run Cypher. Read-only by default — writes and DDL require an explicit --write. A ; batch reports per statement (#2 FAILED: …) with a non-zero exit code; --continue-on-error keeps going
knowledge view [--port N]	Local graph web view (localhost and 127.0.0.1, works offline). Includes a read-only /cypher?q= endpoint
knowledge status	Install, settings, and graph statistics

While the Gateway is running

Only one process can open the graph DB. While the Gateway (gateway start) is receiving consultations, it exposes a query API (http://127.0.0.1:8790/knowledge/, setting knowledge.queryPort), and status, search, view, and read-only query go through it automatically — you do not have to stop the Gateway to query. Only writes (build, query --write) need gateway stop first. You can call it directly too: GET /knowledge/status, /knowledge/cypher?q=, /knowledge/graph.json, /knowledge/search?q=.

Billing notes

Sending commands (send, rich sends, etc.) consume the consultations included in your subscription plan. Lookup and settings commands are not billed. Once you've used up all remaining consultations, sending is blocked; upgrading to a higher plan resumes it.

Discord in-channel commands

While the Gateway (Discord sink) is running, human agents can use /cs-close, /cs-memo, and /cs-who in Discord threads. → Gateway