CLI Full Command Reference

main.py is the command-line interface for the Familiars bridge, wrapping all REST endpoints exposed by 47 route files (excluding the WebSocket-only digital human / phone call streams).

40 command groups, 200+ subcommands. This document is the complete reference.

---

0. Startup Prerequisites

The CLI does not start the bridge. It drives an already-running bridge instance.

# 先确保 bridge 运行
.venv/Scripts/python -m src.bridge.run

# 另开终端
python main.py --help

Authentication

Every request carries the X-Bridge-Token header. The CLI resolves the token with the following priority:

1. --token <value> command-line argument
2. BRIDGE_TOKEN environment variable
3. File pointed to by the BRIDGE_TOKEN_PATH environment variable
4. File specified by the --token-file <path> argument
5. Default: workspace/.bridge_token

Bridge URL

1. --base-url <url> command-line argument
2. BRIDGE_URL environment variable
3. workspace/.bridges.json (written when Electron spawns the bridge; contains PID + port)
4. workspace/.bridge.port (port file written by the bridge)
5. Default: https://127.0.0.1:18711

Global Options

Option	Description
--pretty	Pretty-print JSON output (2-space indent)
--verbose / -v	Print request info to stderr
--base-url	Override the bridge URL
--token	Override the bridge token
--token-file	Specify a token file path
--timeout	HTTP timeout in seconds (default 60)

Body Control

All POST/PUT/PATCH subcommands support:

Option	Description
--field KEY=VALUE	Set body fields one at a time (repeatable; values are auto-parsed as JSON)
--body-json JSON	Full JSON body (overrides --field)
--body-file PATH	Read the JSON body from a file (overrides --body-json)
--query KEY=VALUE	Extra query parameters (repeatable)

File Upload

Subcommands that support multipart/form-data:

Option	Description
--file PATH	Path of the file to upload (required)
--form KEY=VALUE	Additional form fields (repeatable)

---

1. Command Group Overview

#	Group	Description	Subcommands
1	auth	Local identity register/login	2
2	broker	Marketplace author tools + marketplace install + federation/CRL/trust management	20
3	recipe	Recipe author tools: pack/sign/verify/publish + relay review	8
4	flow	Flow template author tools: pack/sign/verify/publish + relay review	8
5	agents	Agent lifecycle + assets	16
6	chat	Chat: send/stream/translate/model list	5
7	dialogues	Dialogue list management	5
8	tree	Dialogue tree structure operations	7
9	todos	Todo CRUD	6
10	schedules	Schedule CRUD	5
11	cron	Scheduled job management	6
12	reminders	Reminders: recent/SSE stream/snooze/dismiss	4
13	settings	Runtime settings (global/agent/dialogue/LLM)	8
14	user	User profile/avatar	5
15	background	Background mode + autorun	4
16	status	Runtime status	3
17	usage	LLM token usage	1
18	memory	Memory writer diagnostics	1
19	learn	Framework docs	2
20	feedback	Proactive message rating	2
21	quick-inputs	Quick input templates	4
22	quick-ask	Hotkey ad-hoc chat	2
23	draft	Auto-classify text into schedules/todos	3
24	reports	Reports + manager meta-review	6
25	responses	OpenAI Responses API proxy	2
26	dev	Development/demo endpoints	2
27	gift	Gift v2	4
28	feishu	Feishu webhook	2
29	monitor	Social listeners	7
30	skills	Skill list/run/SSE	10
31	skill-forge	Skill forging	6
32	skill-workshop	Skill studio (video pipeline)	14
33	cg	CG cutscenes	5
34	asr	ASR speech recognition + prewarm	7
35	digital-human	Digital human REST	4
36	phone-call	Phone call REST	1
37	recipes-library	Recipe marketplace library	3
38	recipes	Recipe CRUD/bind/dry-run/eval	16
39	agent-workshop	External agent import	6
40	agent-assets	Agent asset staging/replacement	9
41	comm	Communication hub (messages/approvals/interrupt)	7
42	flows	Flow instance management	4

---

2. auth — Local Identity

# 注册新本地身份
python main.py auth register --nickname "Alice"

# 登录（当前设备指纹）
python main.py auth login

Subcommand	HTTP	Path	Parameters
register	POST	/api/auth/register	--nickname
login	POST	/api/auth/login	None

---

3. broker — Marketplace

3.1 Local author tools (no bridge required)

# 生成 Ed25519 签名密钥
python main.py broker keygen --name mykey
python main.py broker keygen --name mykey --overwrite   # 覆盖旧密钥

# 列出已有密钥
python main.py broker keys-list

# 打包 broker 目录
python main.py broker pack workspace/manager/brokers/starter_broker
python main.py broker pack workspace/manager/brokers/starter_broker --output custom.broker.zip

# 签名
python main.py broker sign starter_broker.broker.zip --author-key mykey

# 校验
python main.py broker verify starter_broker.broker.zip --pretty

# 一键发布到 relay
python main.py broker publish workspace/manager/brokers/starter_broker \
  --author-key mykey --relay https://api.familiars.cn \
  --author-name "My Broker" --categories "tools,chat"

# 一键发布到本地 host 目录
python main.py broker publish workspace/manager/brokers/starter_broker \
  --author-key mykey --host-dir ./host --download-url-base https://brokers.example.com/

3.2 Marketplace installation (requires bridge)

python main.py broker install --url https://example.com/x.broker.zip \
  --sha256 <64位hex> --pubkey <base64>

# 查看市场 index
python main.py broker marketplace-index

3.3 Federation management

python main.py broker federation-status

3.4 Relay trust management (operator-only)

python main.py broker relay-trust-add --pubkey <b64> --operator-key mykey \
  --relay https://api.familiars.cn --name "Trusted Author" --notes "vouched"

python main.py broker relay-trust-list --relay https://api.familiars.cn

python main.py broker relay-trust-remove --pubkey <b64> --operator-key mykey \
  --relay https://api.familiars.cn

3.5 Relay review

# 查看待审核队列
python main.py broker relay-review-pending --operator-key mykey --relay https://api.familiars.cn

# 审批
python main.py broker relay-review-approve --broker-id starter_broker --version 1.0.0 \
  --operator-key mykey --relay https://api.familiars.cn --note "LGTM"

# 拒绝
python main.py broker relay-review-reject --broker-id starter_broker --version 1.0.0 \
  --note "Missing manifest" --operator-key mykey --relay https://api.familiars.cn

# 查看提交状态
python main.py broker relay-review-status --broker-id starter_broker --version 1.0.0 \
  --author-key mykey --relay https://api.familiars.cn

# 交互式逐条审核
python main.py broker relay-review --operator-key mykey --relay https://api.familiars.cn

3.6 Cluster CRL + trust management

# CRL 吊销
python main.py broker crl-revoke --pubkey <b64> --operator-key mykey --reason "compromised"

# CRL 列表
python main.py broker crl-list

# CRL 取消吊销
python main.py broker crl-unrevoke --pubkey <b64> --operator-key mykey

# 集群信任添加/列表/移除
python main.py broker trust-add --pubkey <b64> --operator-key mykey
python main.py broker trust-list
python main.py broker trust-remove --pubkey <b64> --operator-key mykey

Complete subcommand table

Subcommand	Type	Description	Key parameters
keygen	Local	Generate an Ed25519 signing key	--name --overwrite
keys-list	Local	List existing keys	-
pack	Local	Pack a broker directory into .broker.zip	source_dir --output
sign	Local	Sign a .broker.zip	zip_path --author-key
verify	Local	Verify signature + manifest	zip_path
publish	Local	One-shot pack+sign+publish	source_dir --author-key --relay/--host-dir+--download-url-base --author-name --categories
install	Bridge	Install from a marketplace URL	--url --sha256 --pubkey
marketplace-index	Bridge	View the marketplace index	-
federation-status	Bridge	Federation status	-
relay-trust-add	Local→relay	Add trust	--pubkey --operator-key --relay
relay-trust-list	Local→relay	List trust	--relay
relay-trust-remove	Local→relay	Remove trust	--pubkey --operator-key --relay
relay-review-pending	Local→relay	Pending review list	--operator-key --relay
relay-review-approve	Local→relay	Approve	--broker-id --version --operator-key --relay
relay-review-reject	Local→relay	Reject	--broker-id --version --note --operator-key --relay
relay-review-status	Local→relay	Status query	--broker-id --version --author-key --relay
relay-review	Local→relay	Interactive review	--operator-key --relay
crl-revoke	Local→bridge	CRL revoke	--pubkey --operator-key --reason
crl-list	Local→bridge	CRL list	-
crl-unrevoke	Local→bridge	CRL unrevoke	--pubkey --operator-key
trust-add	Local→bridge	Cluster trust add	--pubkey --operator-key
trust-list	Local→bridge	Cluster trust list	-
trust-remove	Local→bridge	Cluster trust remove	--pubkey --operator-key

---

4. recipe — Recipe Author Tools

python main.py recipe pack workspace/agent_recipes/my_recipe
python main.py recipe sign my_recipe.recipe.zip --author-key mykey
python main.py recipe verify my_recipe.recipe.zip
python main.py recipe publish workspace/agent_recipes/my_recipe \
  --author-key mykey --relay https://api.familiars.cn

Subcommand	Type	Description	Key parameters
pack	Local	Pack into .recipe.zip	source_dir --output
sign	Local	Sign	zip_path --author-key
verify	Local	Verify	zip_path
publish	Local→relay	Pack+sign+upload	source_dir --author-key --relay --author-name --categories
relay-review-pending	Local→relay	Pending review list	--operator-key --relay
relay-review-approve	Local→relay	Approve	--artifact-id --version --operator-key --relay
relay-review-reject	Local→relay	Reject	--artifact-id --version --note --operator-key --relay
relay-review-status	Local→relay	Status query	--artifact-id --version --author-key --relay
relay-review	Local→relay	Interactive review	--operator-key --relay

---

5. flow — Flow Template Author Tools

Same structure as recipe, except the packaged target is a flow template directory.

Subcommand	Type	Description	Key parameters
pack	Local	Pack into .flow.zip	source_dir --output
sign	Local	Sign	zip_path --author-key
verify	Local	Verify	zip_path
publish	Local→relay	Pack+sign+upload	source_dir --author-key --relay
relay-review-pending	Local→relay	Pending review list	--operator-key --relay
relay-review-approve	Local→relay	Approve	--artifact-id --version --operator-key --relay
relay-review-reject	Local→relay	Reject	--artifact-id --version --note --operator-key --relay
relay-review-status	Local→relay	Status query	--artifact-id --version --author-key --relay
relay-review	Local→relay	Interactive review	--operator-key --relay

---

6. agents — Agent Lifecycle

python main.py agents list --pretty
python main.py agents create --agent-id 5
python main.py agents create-stream --name "小助手" --identity "温柔体贴" --personality "幽默"
python main.py agents delete 5
python main.py agents avatar 1 --output avatar.png
python main.py agents portrait 1 --output portrait.png
python main.py agents figure-rgba 1 --output figure.png
python main.py agents bust-loop 1 --output bust.webp
python main.py agents diagnose-dirs

Subcommand	HTTP	Path	Key parameters
list	GET	/api/agents	-
create	POST	/api/agents	--agent-id
create-stream	SSE	GET /api/agents/create/stream	--name --identity --personality --appearance --voice --need-figure --need-audio --figure-staging-id --voice-staging-id --voice-transcript
delete	DELETE	/api/agents/{agent_id}	agent_id
greeting-played	POST	/api/agents/{agent_id}/greeting/played	agent_id
greeting-video	GET	/api/agents/{agent_id}/greeting	agent_id --output
diagnose-dirs	GET	/api/agents/diagnose-dirs	-
avatar	GET	/api/agents/{agent_id}/avatar	agent_id --output
portrait	GET	/api/agents/{agent_id}/portrait	agent_id --output
figure-rgba	GET	/api/agents/{agent_id}/figure_rgba	agent_id --output
bust-loop	GET	/api/agents/{agent_id}/bust_loop	agent_id --output
bust-meta	GET	/api/agents/{agent_id}/bust_meta	agent_id
theme-element	GET	/api/agents/{agent_id}/theme/{element}	agent_id element --output
theme-meta	GET	/api/agents/{agent_id}/theme/meta	agent_id
skill-cg	GET	/api/agents/{agent_id}/skills/{skill_id}/cg	agent_id skill_id --output
manager-entry-image	GET	/api/manager/entry-image/{key}	key --output

---

7. chat — Chat

# 发送消息，获取完整 JSON 回复
python main.py chat send --prompt "你好" --agent-id 1

# SSE 流式输出
python main.py chat stream --prompt "今天有什么待办？" --agent-id 1

# 翻译
python main.py chat translate --text "Hello World" --target zh

# 列出可用模型
python main.py chat models

Subcommand	HTTP	Path	Key parameters
send	POST	/api/chat/send	--prompt --agent-id --dialogue-id --parent-id --type --call-mode
stream	SSE	GET /api/chat/stream	--prompt --agent-id --dialogue-id --parent-id --type --model --regen-q --resume-a --call-mode
generate-stream	SSE	GET /api/chat/generate/stream	--prompt --agent-id
translate	POST	/api/translate	--text --target
models	GET	/api/models	-

---

8. dialogues — Dialogue List

python main.py dialogues list 1
python main.py dialogues create 1 --topic "新对话"
python main.py dialogues rename 1 3 --topic "重命名"
python main.py dialogues mark-read 1 3
python main.py dialogues delete 1 3

Subcommand	HTTP	Path	Key parameters
list	GET	/api/dialogues/{agent_id}	agent_id
create	POST	/api/dialogues/{agent_id}	agent_id --topic
rename	PATCH	/api/dialogues/{agent_id}/{dialogue_id}	agent_id dialogue_id --topic
mark-read	POST	/api/dialogues/{agent_id}/{dialogue_id}/read	agent_id dialogue_id
delete	DELETE	/api/dialogues/{agent_id}/{dialogue_id}	agent_id dialogue_id

---

9. tree — Dialogue Tree

python main.py tree get 1 1
python main.py tree query 1 1 --text "报销流程" --k 5
python main.py tree node 1 1 42
python main.py tree path 1 1 42
python main.py tree delete 1 1 42
python main.py tree move 1 1 --node-id 42 --new-parent-id 10
python main.py tree edit 1 1 42 --content "修改后的内容"

Subcommand	HTTP	Path	Key parameters
get	GET	/api/tree/{agent_id}/{dialogue_id}	agent_id dialogue_id
query	GET	/api/tree/{agent_id}/{dialogue_id}/query	agent_id dialogue_id --text --k
node	GET	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id
path	GET	/api/tree/{agent_id}/{dialogue_id}/path/{node_id}	agent_id dialogue_id node_id
delete	DELETE	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id
move	POST	/api/tree/{agent_id}/{dialogue_id}/move	agent_id dialogue_id --node-id --new-parent-id
edit	PATCH	/api/tree/{agent_id}/{dialogue_id}/node/{node_id}	agent_id dialogue_id node_id --content

---

10. todos — Todos

python main.py todos list
python main.py todos create --title "买牛奶" --deadline 2026-07-05T18:00
python main.py todos patch 3 --title "买全脂牛奶"
python main.py todos complete 3
python main.py todos uncomplete 3
python main.py todos delete 3

Subcommand	HTTP	Path	Key parameters
list	GET	/api/todos	--open-only
create	POST	/api/todos	--title --content --deadline --emergency-level --needs-reminder --remind-at --frequency
patch	PATCH	/api/todos/{todo_id}	todo_id --title --content --deadline --emergency-level
complete	POST	/api/todos/{todo_id}/complete	todo_id
uncomplete	POST	/api/todos/{todo_id}/uncomplete	todo_id
delete	DELETE	/api/todos/{todo_id}	todo_id

---

11. schedules — Schedules

python main.py schedules list --agent-id 1
python main.py schedules create --title "会议" --scheduled-time 2026-08-30T14:00:00
python main.py schedules complete 5
python main.py schedules uncomplete 5
python main.py schedules delete 5

Subcommand	HTTP	Path	Key parameters
list	GET	/api/schedules	--agent-id
create	POST	/api/schedules	--title --content --scheduled-time --emergency-level --frequency --kind --needs-reminder --remind-at
complete	POST	/api/schedules/{schedule_id}/complete	schedule_id
uncomplete	POST	/api/schedules/{schedule_id}/uncomplete	schedule_id
delete	DELETE	/api/schedules/{schedule_id}	schedule_id

---

12. cron — Scheduled Jobs

python main.py cron list --agent-id 1
python main.py cron create --name "morning_report" --cron "0 9 * * *" --task "生成每日报告" --agent-id 1
python main.py cron patch morning_report --cron "30 9 * * *"
python main.py cron runs morning_report --limit 10
python main.py cron run-now morning_report
python main.py cron delete morning_report

Subcommand	HTTP	Path	Key parameters
list	GET	/api/cron-jobs	--agent-id --include-system
create	POST	/api/cron-jobs	--name --cron --task --agent-id --action --recurring
patch	PATCH	/api/cron-jobs/{name}	name --new-name --cron --task --action --recurring --agent-id
delete	DELETE	/api/cron-jobs/{name}	name
runs	GET	/api/cron-jobs/{name}/runs	name --limit
run-now	POST	/api/cron-jobs/{name}/run-now	name

---

13. reminders — Reminders

python main.py reminders recent --since-ts 1725000000 --limit 20
python main.py reminders stream --start-ts 1725000000
python main.py reminders snooze todo 3 --minutes 15
python main.py reminders dismiss schedule 5

Subcommand	HTTP	Path	Key parameters
recent	GET	/api/reminders/recent	--since-ts --limit
stream	SSE	GET /api/reminders/stream	--start-ts
snooze	POST	/api/reminders/{kind}/{subject_id}/snooze	kind(schedule/todo) subject_id --minutes
dismiss	POST	/api/reminders/{kind}/{subject_id}/dismiss	kind subject_id

---

14. settings — Runtime Settings

python main.py settings get
python main.py settings put --body-json '{"color":"red"}'
python main.py settings get-agent 1
python main.py settings put-agent 1 --body-json '{"need_initiative":false}'
python main.py settings get-llm
python main.py settings put-llm --base-url https://api.openai.com/v1 --api-key sk-xxx

Subcommand	HTTP	Path	Key parameters
get	GET	/api/settings	-
put	PUT	/api/settings	JSON body
get-agent	GET	/api/agents/{agent_id}/settings	agent_id
put-agent	PUT	/api/agents/{agent_id}/settings	agent_id JSON body
get-dialogue	GET	/api/dialogues/{agent_id}/{dialogue_id}/settings	agent_id dialogue_id
put-dialogue	PUT	/api/dialogues/{agent_id}/{dialogue_id}/settings	agent_id dialogue_id JSON body
get-llm	GET	/api/settings/llm	-
put-llm	PUT	/api/settings/llm	--base-url --api-key --default-model --transport-mode --auto-fallback

---

15. user — User Profile

python main.py user profile-get
python main.py user profile-put --body-json '{"nickname":"Alice"}'
python main.py user avatar-get --output my_avatar.png
python main.py user avatar-upload --file avatar.png
python main.py user intro --text "我是一名开发者"

Subcommand	HTTP	Path	Key parameters
profile-get	GET	/api/user/profile	-
profile-put	PUT	/api/user/profile	JSON body
avatar-get	GET	/api/user/avatar	--output
avatar-upload	POST	/api/user/avatar	--file
intro	POST	/api/user/intro	--text

---

16. background — Background Mode

Subcommand	HTTP	Path
state	GET	/api/background/state
enable	POST	/api/background/enable
disable	POST	/api/background/disable
quit	POST	/api/background/quit

---

17. status — Runtime Status

Subcommand	HTTP	Path	Key parameters
get	GET	/api/status	-
stream	SSE	GET /api/status/stream	-
debug	POST	/api/status/debug	--key --label --detail --level --clear

---

18. usage — LLM Usage

python main.py usage summary --model gpt-4o

Subcommand	HTTP	Path	Key parameters
summary	GET	/api/usage/summary	--model

---

19. memory — Memory Diagnostics

python main.py memory writer-status --recent 30 --agent-id 1

Subcommand	HTTP	Path	Key parameters
writer-status	GET	/api/memory/writer-status	--recent --agent-id

---

20. learn — Framework Docs

Subcommand	HTTP	Path	Key parameters
docs	GET	/api/learn/docs	-
doc	GET	/api/learn/docs/{doc_key}	doc_key

---

21. feedback — Proactive Message Rating

Subcommand	HTTP	Path	Key parameters
proactive	POST	/api/feedback/proactive	--agent-id --rating(0/1) --decision-id --fired-at --signal-summary --action-category --act-score
stats	GET	/api/feedback/proactive/stats	--agent-id

---

22. quick-inputs — Quick Inputs

Subcommand	HTTP	Path	Key parameters
list	GET	/api/quick-inputs	-
add	POST	/api/quick-inputs	--text
use	POST	/api/quick-inputs/{qid}/use	qid
delete	DELETE	/api/quick-inputs/{qid}	qid

---

23. quick-ask — Quick Ask

Subcommand	HTTP	Path	Key parameters
create	POST	/api/quick_ask/dialogue	--quoted-text
archive	POST	/api/quick_ask/dialogue/{dialogue_id}/archive	dialogue_id

---

24. draft — Text Classification Drafts

Subcommand	HTTP	Path	Key parameters
auto	POST	/api/draft/from_text	--text --agent-id
schedule	POST	/api/draft/schedule_from_text	--text --agent-id
todo	POST	/api/draft/todo_from_text	--text --agent-id

---

25. reports — Reports

Subcommand	HTTP	Path	Key parameters
list	GET	/api/manager/reports	-
by-agent	GET	/api/manager/reports/by-agent	-
meta	GET	/api/manager/reports/meta	-
content	GET	/api/manager/reports/content	--path
roll-up	POST	/api/manager/reports/roll-up	-
run-legacy	POST	/api/manager/report	--period

---

26. responses — OpenAI Responses API Proxy

Subcommand	HTTP	Path	Key parameters
proxy	POST	/v1/responses	JSON body (--body-file/--body-json)
proxy-stream	SSE	POST /v1/responses	JSON body (streaming)

---

27. dev — Development Endpoints

Subcommand	HTTP	Path
fake-gift	POST	/api/dev/fake_gift
gift-demo	POST	/api/dev/gift_demo

---

28. gift — Gift v2

Subcommand	HTTP	Path	Key parameters
video	GET	/api/gift/video/{decision_id}	decision_id --output
swap	POST	/api/gift/swap	--agent-id --dialogue-id --node-id --candidate-index --keyword
open	POST	/api/gift/open	--agent-id --dialogue-id --node-id
purchase	POST	/api/gift/purchase	--agent-id --dialogue-id --node-id

---

29. feishu — Feishu

Subcommand	HTTP	Path	Key parameters
test-webhook	POST	/api/feishu/test_webhook	--webhook-url --title --content
webhook	POST	/api/feishu/webhook	JSON body

---

30. monitor — Message Listening

python main.py monitor list
python main.py monitor diag
python main.py monitor start wechat
python main.py monitor stop wechat
python main.py monitor settings-get
python main.py monitor file-roots
python main.py monitor file-roots-refresh --source wechat

Subcommand	HTTP	Path	Key parameters
list	GET	/api/monitor	-
settings-get	GET	/api/monitor/settings	-
settings-put	PUT	/api/monitor/settings	JSON body
file-roots	GET	/api/monitor/file-roots	-
file-roots-refresh	POST	/api/monitor/file-roots/refresh	--source(wechat/qq) --allow-ui-probe
diag	GET	/api/monitor/_diag	-
start	POST	/api/monitor/{monitor_id}/start	monitor_id
stop	POST	/api/monitor/{monitor_id}/stop	monitor_id

---

31. skills — Skills

python main.py skills list
python main.py skills run 1 my_skill
python main.py skills stream run_abc123
python main.py skills agent-list 1
python main.py skills run-in-dialogue 1 my_skill --dialogue-id 3
python main.py skills doc my_skill
python main.py skills cancel-run run_abc123

Subcommand	HTTP	Path	Key parameters
list	GET	/api/skills	-
cancel-run	POST	/api/skills/runs/{run_id}/cancel	run_id
unschedule	POST	/api/agents/{agent_id}/skills/{skill_id}/unschedule	agent_id skill_id
active	GET	/api/skills/runs/active	-
stream	SSE	GET /api/skills/runs/{run_id}/stream	run_id
agent-list	GET	/api/agents/{agent_id}/skills	agent_id
doc	GET	/api/skills/{skill_id}/doc	skill_id
kb	GET	/api/agents/{agent_id}/knowledge-bases	agent_id
run	POST	/api/agents/{agent_id}/skills/{skill_id}/run	agent_id skill_id
run-in-dialogue	POST	/api/agents/{agent_id}/skills/{skill_id}/run_in_dialogue	agent_id skill_id --dialogue-id --parent-id

---

32. skill-forge — Skill Forging

Subcommand	HTTP	Path	Key parameters
propose	POST	/api/skills/forge/from-dialogue/propose	JSON body
repropose	POST	/api/skills/forge/from-dialogue/repropose	JSON body
summary	POST	/api/skills/forge/summary	JSON body
preview	POST	/api/skills/forge/preview	JSON body
revise	POST	/api/skills/forge/revise	--skill-md --user-guidance --skill-id
commit	POST	/api/skills/forge/commit	--skill-id --skill-md --scope(global/agent) --agent-id --overwrite

---

33. skill-workshop — Skill Studio

Subcommand	HTTP	Path	Key parameters
list	GET	/api/skill_workshop/skills	-
upload	POST	/api/skill_workshop/upload	--file
asset-get	GET	/api/skill_workshop/asset	--output
rewrite	POST	/api/skill_workshop/rewrite	JSON body
run	POST	/api/skill_workshop/run	JSON body
status	GET	/api/skill_workshop/run/{run_id}/status	run_id
images	GET	/api/skill_workshop/run/{run_id}/images	run_id
regen-image	POST	/api/skill_workshop/run/{run_id}/regenerate_image	run_id JSON body
approve-images	POST	/api/skill_workshop/run/{run_id}/approve_images	run_id JSON body
clips	GET	/api/skill_workshop/run/{run_id}/clips	run_id
clip-gen	POST	/api/skill_workshop/run/{run_id}/clips/{idx}/generate	run_id idx JSON body
concat-final	POST	/api/skill_workshop/run/{run_id}/concat_final	run_id JSON body
history	GET	/api/skill_workshop/history/{skill_id}	skill_id
history-run	GET	/api/skill_workshop/history/{skill_id}/{run_id}	skill_id run_id

---

34. cg — CG Cutscenes

Subcommand	HTTP	Path	Key parameters
list	GET	/api/agents/manager/cg/list	-
run	POST	/api/agents/manager/cg/run	--target-agent-id --target-skill-id --prompt
delete	DELETE	/api/agents/{agent_id}/skills/{skill_id}/cg	agent_id skill_id
skill-state	GET	/api/skill_state	-
preview	POST	/api/agents/{agent_id}/skills/{skill_id}/cg/preview	agent_id skill_id --seconds

---

35. asr — Speech Recognition

Subcommand	HTTP	Path	Key parameters
transcribe	POST	/api/asr/transcribe	--file --language
prewarm	POST	/api/asr/prewarm	-
call-prewarm	POST	/api/call/prewarm	--agent-id
dialog-prewarm	POST	/api/dialog/prewarm	-
focus	POST	/api/focus/{mode}	mode(dialog/call/idle) --agent-id --dialogue-id
gpu-tier	GET	/api/gpu_tier	-
model-choice	POST	/api/model_choice	--model-id --choice(download/skip/never_prompt)

---

36. digital-human — Digital Human

Subcommand	HTTP	Path	Key parameters
status	GET	/api/digital_human/{agent_id}/status	agent_id
prewarm	POST	/api/digital_human/{agent_id}/prewarm	agent_id
unload	POST	/api/digital_human/{agent_id}/unload	agent_id
regen-voice	POST	/api/digital_human/{agent_id}/regenerate_voice	agent_id

---

37. phone-call — Phone Calls

Subcommand	HTTP	Path	Key parameters
status	GET	/api/phone_call/{agent_id}/status	agent_id

---

38. recipes-library — Recipe Marketplace Library

Subcommand	HTTP	Path	Key parameters
list	GET	/api/recipes/library	-
install	POST	/api/recipes/library/install	--library-id --overwrite
publish	POST	/api/recipes/library/publish	--recipe-id --channel --author --version

---

39. recipes — Recipe CRUD

python main.py recipes list
python main.py recipes get my_recipe
python main.py recipes catalog
python main.py recipes create --body-file manifest.json
python main.py recipes bind my_recipe 1
python main.py recipes validate my_recipe --body-json '{"section":"manifest"}'
python main.py recipes dry-run my_recipe --prompt "你好" --mock-response "模拟回复"
python main.py recipes eval my_recipe --agent-id 1 --timeout 120
python main.py recipes export-zip my_recipe --output my_recipe.zip
python main.py recipes import-zip --file my_recipe.zip

Subcommand	HTTP	Path	Key parameters
catalog	GET	/api/recipes/catalog	-
protocol	GET	/api/recipes/_meta/protocol	-
list	GET	/api/recipes	-
get	GET	/api/recipes/{recipe_id}	recipe_id
export-zip	GET	/api/recipes/{recipe_id}/export_zip	recipe_id --output
import-zip	POST	/api/recipes/import_zip	--file
import-folder	POST	/api/recipes/import_folder	JSON body
create	POST	/api/recipes	JSON body
update	PUT	/api/recipes/{recipe_id}	recipe_id JSON body
delete	DELETE	/api/recipes/{recipe_id}	recipe_id
bind	POST	/api/recipes/{recipe_id}/bind/{agent_id}	recipe_id agent_id
unbind	POST	/api/recipes/{recipe_id}/unbind/{agent_id}	recipe_id agent_id
validate	POST	/api/recipes/{recipe_id}/validate	recipe_id JSON body
chain-source	GET	/api/recipes/chain_source/{slot}	slot
dry-run	POST	/api/recipes/{recipe_id}/dry-run	recipe_id --prompt --mock-response
eval	POST	/api/recipes/{recipe_id}/eval	recipe_id --agent-id --suite --max-cases --timeout --parallelism --save-baseline

---

40. agent-workshop — External Agent Import

Subcommand	HTTP	Path	Key parameters
kinds	GET	/api/agent_workshop/kinds	-
scan	GET	/api/agent_workshop/scan/{kind}	kind
import-start	POST	/api/agent_workshop/import/{kind}/start	kind --need-digital-human --display-name --model
import-cancel	POST	/api/agent_workshop/import/cancel	--session-id
import-stream	SSE	GET /api/agent_workshop/import/{kind}/stream	kind --session-id --approved-steps
custom	POST	/api/agent_workshop/custom	--display-name --repo-url --cli-command --description --need-digital-human

---

41. agent-assets — Agent Asset Management

Subcommand	HTTP	Path	Key parameters
upload-staging	POST	/api/agents/upload_staging	--file --kind(figure/voice)
figure-job-start	POST	/api/agents/{agent_id}/asset_job/figure	agent_id --file
job-status	GET	/api/agents/{agent_id}/asset_job	agent_id
job-stream	SSE	GET /api/agents/{agent_id}/asset_job/stream	agent_id
job-retry	POST	/api/agents/{agent_id}/asset_job/retry	agent_id --stage
job-dismiss	DELETE	/api/agents/{agent_id}/asset_job	agent_id
job-upload-stage	POST	/api/agents/{agent_id}/asset_job/upload_stage	agent_id --file --stage
voice-replace	POST	/api/agents/{agent_id}/voice/replace	agent_id --file --transcript
greeting-regen	POST	/api/agents/{agent_id}/greeting/regenerate	agent_id

---

42. comm — Communication Hub

python main.py comm messages --agent-id 1
python main.py comm post --body-json '{"agent_id":1,"content":"你好"}'
python main.py comm approvals-pending --agent-id 1
python main.py comm approval-respond --request-id req_abc --approved true --scope always
python main.py comm interrupt --agent-id 1 --reason "停！"

Subcommand	HTTP	Path	Key parameters
messages	GET	/api/communication/messages	--agent-id --since --direction(agent_to_user/user_to_agent)
post	POST	/api/communication/messages	JSON body
send	POST	/api/communication/send	JSON body
approvals-pending	GET	/api/communication/approvals/pending	--agent-id
approval-request	POST	/api/communication/approvals/request	JSON body
approval-respond	POST	/api/communication/approvals/respond	--request-id --approved --reason --scope
approval-status	GET	/api/communication/approvals/{request_id}	request_id
interrupt	POST	/api/communication/interrupt	--agent-id --reason

---

43. flows — Flow Instances

python main.py flows list --status running
python main.py flows get flow_abc123 --trace-tail 50
python main.py flows trace flow_abc123 --tail 100
python main.py flows cancel flow_abc123

Subcommand	HTTP	Path	Key parameters
list	GET	/api/flows	--status --template-id --limit
get	GET	/api/flows/{instance_id}	instance_id --trace-tail
trace	GET	/api/flows/{instance_id}/trace	instance_id --tail
cancel	POST	/api/flows/{instance_id}/cancel	instance_id

---

44. Output Formats

• JSON responses: single-line JSON by default. Add --pretty for formatted output.
• SSE streams: one JSON event per line. [DONE] marks the end of the stream.
• File downloads: --output <path> specifies the save path; by default outputs a {ok, path, bytes} JSON.
• Errors: HTTP ≥ 400 prints ! HTTP <status> to stderr.

---

45. Typical Usage

# 完整工作流：创建 agent → 绑定 recipe → 开始对话
python main.py agents create --agent-id 5
python main.py recipes bind medical_triage 5
python main.py chat stream --prompt "分析这个病例" --agent-id 5

# 监控管理
python main.py monitor list
python main.py monitor start wechat
python main.py monitor start qq

# 技能开发
python main.py skill-forge propose --body-file proposal.json
python main.py skill-forge preview --body-file draft.json
python main.py skill-forge commit --skill-id my_skill --skill-md "$(cat SKILL.md)" --scope global

# Broker 开发完整流程
python main.py broker keygen --name mykey
python main.py broker pack workspace/manager/brokers/my_broker
python main.py broker sign my_broker.broker.zip --author-key mykey
python main.py broker verify my_broker.broker.zip --pretty
python main.py broker publish workspace/manager/brokers/my_broker \
  --author-key mykey --relay https://api.familiars.cn