명령어 레퍼런스

talkbridge <명령> [옵션]. 인증이 필요한 명령은 먼저 setup / login으로 키를 등록해야 합니다.

옵션 표기: --channel 대상 채널의 키 · --to(=--user) 대상 고객 키 · 대부분의 명령에서 --channel 은 필수입니다.

--channel 에 넣는 값은 Brand Key(채널 키)입니다. 톡브릿지 센터 개발자 모드 「연동 키 안내」 에서 확인하거나, talkbridge whoami 의 상담 가능 채널 목록에서 고릅니다. API 의 brandKey 와 같은 값입니다.

채널마다 키가 하나씩 있습니다. 한 브랜드에 카카오·LINE·네이버 채널을 연결했다면 키도 세 개입니다.
--channel 은 CLI v1.2.0 부터 쓸 수 있습니다. 이전 이름 --brand 도 그대로 동작하므로, v1.1 이하 CLI 에서는 --brand 를 쓰면 됩니다.

전역 옵션 --json — 어느 명령에나 붙이면 사람이 읽는 텍스트 대신 한 줄 JSON 을 출력합니다(프로그램 연동용, JSON 출력 참고).

전체 명령

명령	동작	주요 옵션
`setup [<키>]`	키 검증·저장 / 인자 없으면 TUI. 옵션 전체는 `setup --help`(부수효과 없음)	`--endpoint`, sink·CRM·AI 플래그, `--dry-run`
`login`	웹 OAuth 페어링으로 키 발급·저장	`--console`, `--endpoint`
`whoami`	내 이름·권한·엔드포인트·상담 가능 채널(브랜드별)	—
`env`	이 실행파일의 채널·바라보는 서버·설정 경로·바이너리 경로 확인(인증 불필요)	`--json` → `binaryPath`·`launcherPath`
`history`	상담 이력(진행중/완료, convId)	`--channel`
`rooms`	상담방 리스트 / 특정 방 메시지	`--channel`(필수), `--user`, `--max N`
`send`	텍스트/리치/첨부 발송	`--channel`, `--to`, `--text`, `--rich-json <파일>`, `--file <경로>`(반복 가능)
`delete`	보낸 메시지 삭제 — 발송 후 24시간 내	`--channel`, `--to`, `--serial <발신번호>` 또는 `--text <본문> [--within <초>]`
`profile`	발신프로필 조회	`--channel`(필수)
`webhook-domain`	수신도메인 조회/설정	`get`/`set`, `--channel`, `--url`
`chat`	채팅기능 토글	`activate`/`deactivate`, `--channel`
`schedule`	상담시간 조회/설정	`get`/`set`, `--channel`, `--json <파일>`
`block` / `unblock`	사용자 차단 / 해제	`--channel`, `--to`
`end-with-bot`	종료 + 봇 전환(handoff)	`--channel`, `--to`, `--event`
`personal-info`	개인정보 제공 동의 요청(카카오) — 결과는 웹훅 `personal_info`	`--channel`, `--to`
`sysmsg`	시스템메시지 조회	`--channel`(필수)
`upload`	멀티미디어 업로드	`image`/`file`/`audio`/`video`, `--channel`, `--file`
`gateway`	아웃바운드 게이트웨이 데몬	`start`/`stop`/`restart`/`status` → 게이트웨이
`knowledge`	상담지식 온톨로지(그래프 RAG) → 아래	`status`/`install`/`build`/`search`/`query`/`view`
`model`	AI 모델 조회·선택	`list` / `set <id>`
`chatbot`	AI 상담 보조 대화형 TUI	(setup·model 선행)

CLI 와 REST 의 차이

첨부 발송은 CLI send --file(고객에게 바로 전달) 로, REST 는 POST /api/agent/send/attachments 로 합니다. upload 는 URL 만 돌려줍니다.
인사말만 보내고 종료(POST /api/agent/end)는 REST 에만 있고 CLI 에는 없습니다 — CLI 는 end-with-bot(종료+봇 전환)만 제공합니다.
설정 변경 3종(webhook-domain set, chat activate|deactivate, schedule set)은 Admin 스코프 키가 필요합니다. BrandWrite 키로는 조회만 됩니다(403 FORBIDDEN).

자주 쓰는 예시

내 정보 · 이력

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

whoami 는 이 키로 상담할 수 있는 채널을 브랜드별로 묶어 보여 줍니다. 가운데 열이 --channel 에 넣는 키입니다.

상담 가능 채널 (3):   ← send·rooms 등의 --channel <채널키>
  마이브랜드 (브랜드 mybrand-1a2b3c)
    - 카카오  mychannel               상담톡 채널
    - LINE    ch-5d6e7f               LINE 공식계정
    - 네이버  ch-8a9b0c               네이버 톡톡

발신 (텍스트)

talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --text "안녕하세요"

발신 (리치)

리치 봉투 JSON 파일을 만들어 전달합니다. chat_bubble_type 는 필수이며, 발신 식별 필드는 서버가 채웁니다.

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

봉투 스키마와 예시 3종은 발신 API → 리치 봉투 스키마에 있습니다.

발신 (첨부)

이미지·파일을 고객에게 바로 보냅니다. 서버가 카카오에 업로드한 뒤 말풍선(이미지=리치 IMAGE, 파일=플레인 FILE)으로 조립합니다. --text 를 함께 주면 첫 말풍선에 실립니다.

talkbridge send --channel mychannel --to Ab3d_x9Kq2Lm --file ./photo.png --file ./manual.pdf --text "요청하신 자료입니다"

발신 취소(삭제)

send 결과에 표시된 발신번호(serial)로 지우거나, 번호를 모르면 보낸 본문으로 최근 발신을 찾아 지웁니다.

talkbridge delete --channel mychannel --to Ab3d_x9Kq2Lm --serial 1234567890
talkbridge delete --channel mychannel --to Ab3d_x9Kq2Lm --text "안녕하세요" --within 600

발송 후 24시간 안에만 삭제할 수 있습니다. 고객 채팅방에는 「메시지가 삭제되었습니다」 안내가 표시됩니다.
삭제해도 상담 건수는 되돌아오지 않습니다.
개인정보 제공 동의·카카오톡 인증 말풍선은 삭제할 수 없습니다.
--text 는 본문이 정확히 일치해야 찾습니다. 못 찾으면 --within(초, 10~86400)을 늘리거나 --serial 을 직접 지정하세요.

채널 설정

# 수신도메인
talkbridge webhook-domain set --channel mychannel --url https://hook.example.com
# 채팅기능 토글
talkbridge chat activate --channel mychannel
# 상담시간 (JSON 파일로)
talkbridge schedule set --channel mychannel --json schedule.json

고객 관리 · 핸드오프

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

업로드

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

JSON 출력 (`--json`)

어느 명령에나 --json 을 붙이면 텍스트 대신 한 줄 JSON 을 stdout 으로 냅니다. 진단 메시지는 stderr 로 가고, 오류는 {"ok":false,"error":"…","code":"…"} 로 옵니다. 필드명은 REST 응답과 같은 이름(userKey·lastSeq·timestampUnixMs·kind·text …)이라, CLI 로 시작한 연동을 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 "안녕하세요" --json   # {"ok":true,"brandKey":…,"userKey":…,"serial":"bw-…"}
talkbridge whoami --json · env --json · gateway status --json · knowledge status --json

텍스트 모드의 시각 표기도 연도를 포함합니다(2026-09-08 10:28) — 텍스트를 파싱하던 기존 코드가 연말 경계를 추정할 필요가 없습니다.

프로그램에서 호출하기

스크립트·서버에서 CLI 를 spawn 할 때는 바이너리를 직접 실행하세요. npm 이 만드는 .cmd shim 을 Windows 에서 spawn 하면 최신 Node(18.20+/20.12+)가 거부하고(EINVAL), shell: true 로 우회하면 상담 메시지의 " & % ^ 가 cmd 파서에 먹혀 깨지거나 인젝션이 됩니다.

talkbridge env --json 으로 경로를 읽습니다 — 탐색 로직이 필요 없습니다.

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

binaryPath 를 인자 배열로 spawn 합니다(shell 없음). launcherPath 가 있으면 process.execPath 로 그 JS 를 실행해도 됩니다.

const { execFileSync, spawn } = require('node:child_process');
const env = JSON.parse(execFileSync('talkbridge', ['env', '--json'], { shell: process.platform === 'win32' }));
// 이후에는 shell 없이 바이너리를 직접 — 메시지에 어떤 문자가 있어도 그대로 전달된다
const child = spawn(env.binaryPath, [...env.binaryArgs, 'send', '--channel', 'mychannel', '--to', userKey, '--text', text, '--json'],
  { stdio: ['ignore', 'pipe', 'pipe'] });

타임아웃으로 강제 종료할 때는 프로세스 트리를 끝내세요(Windows taskkill /T /F /PID). 런처(node)만 죽이면 바이너리가 살아남아 그래프 DB 잠금을 쥘 수 있습니다. 바이너리를 직접 spawn 했다면 그 프로세스 하나만 끝내면 됩니다.
런처(launcherPath)는 SIGINT/SIGTERM/SIGHUP 을 자식에게 전파합니다.

상담지식 온톨로지 (`knowledge`)

상담을 고객→문의→응답 그래프(LadybugDB, 로컬 임베디드)로 쌓고 검색합니다. AI 는 선택입니다 — 엔티티(의미 단어) 추출과 자연어 검색에만 필요하고, 설치·적재·Cypher 검색은 AI 없이 됩니다.

명령	동작
`knowledge install`	LadybugDB lib 설치 + 활성 + 스키마 (AI 불필요)
`knowledge build [--channel <키>]`	과거 상담 일괄 적재. `Inquiry.ts`/`Response.ts` 는 원 메시지 시각, 적재 시각은 `loadedAt`
`knowledge search --cypher "<Cypher>"`	읽기전용 Cypher(MATCH/RETURN). 전체 컬럼 출력, `--json` 은 `{"columns":[…],"types":[…],"rows":[[…]]}` (숫자·불리언 타입 보존)
`knowledge search "<자연어>"`	AI 키워드 추출 → 노드 매칭 (AI 미설정이면 `--cypher` 를 안내)
`knowledge query [--write] "<Cypher>[; …]"`	Cypher 실행. 기본 읽기전용 — 쓰기·DDL 은 `--write` 를 명시해야 실행. `;` 배치는 문장별 결과(`#2 FAILED: …`)와 종료 코드 ≠ 0, `--continue-on-error` 로 계속
`knowledge view [--port N]`	로컬 그래프 웹뷰(`localhost`·`127.0.0.1` 모두, 오프라인 동작). `/cypher?q=` 읽기전용 엔드포인트 포함
`knowledge status`	설치·설정·그래프 통계

게이트웨이가 떠 있을 때

그래프 DB 는 한 프로세스만 열 수 있습니다. 게이트웨이(gateway start)가 상담을 받는 동안에는 게이트웨이가 조회 API(http://127.0.0.1:8790/knowledge/, 설정 knowledge.queryPort)를 열고, status·search·view·읽기 query 는 그 API 를 자동으로 경유합니다 — 게이트웨이를 내리지 않아도 조회됩니다. 쓰기(build, query --write)만 gateway stop 후 실행하세요. 직접 호출도 됩니다: GET /knowledge/status · /knowledge/cypher?q= · /knowledge/graph.json · /knowledge/search?q=.

과금 유의

발신형 명령(send, 리치 발송 등)은 구독 플랜에 포함된 상담 건수를 소진합니다. 조회·설정 명령은 비과금입니다. 남은 건수를 모두 소진하면 발송이 차단되며, 상위 플랜으로 업그레이드하면 재개됩니다.

디스코드 인채널 커맨드

게이트웨이(Discord sink)가 가동 중이면 상담원이 디스코드 스레드에서 /cs-close, /cs-memo, /cs-who 를 쓸 수 있습니다. → 게이트웨이

전체 명령​

자주 쓰는 예시​

내 정보 · 이력​

발신 (텍스트)​

발신 (리치)​

발신 (첨부)​

발신 취소(삭제)​

채널 설정​

고객 관리 · 핸드오프​

업로드​

JSON 출력 (--json)​

프로그램에서 호출하기​

상담지식 온톨로지 (knowledge)​

과금 유의​