FormLM

formlm-cli

FormLM 的官方 CLI 和 MCP 服务 — 让 AI Agent 直接构建和管理表单。

关键词：FormLM CLI、MCP 服务、AI Agent 表单构建器、表单自动化、测评平台 CLI、Claude MCP、Cursor MCP、AI 驱动的表单、formlm-cli、npm CLI 工具

---

什么是 FormLM？

FormLM 是一个 AI 驱动的表单与测评平台。你可以通过自然语言指令创建智能表单、评分测验和专业评估报告。

使用 formlm-cli，你可以直接在终端中控制 FormLM，或将其接入任何 AI Agent（Claude、Cursor、GPT 等），作为 MCP 服务使用 — 无需 UI。

访问官方网站：https://formlm.me

formlm-cli 已列入官方 MCP 注册表，名称为 me.formlm/cli — 在任何支持 MCP 的客户端（Claude Desktop、Cursor、VS Code Copilot、Codex CLI）中搜索“formlm”即可安装。

---

v0.5.4 新增内容

全方位结构化输出：全部 10 个 MCP 工具现在都声明了 outputSchema，并在每种调用路径（成功、部分成功和错误）中返回可供机器校验的 structuredContent — auth_login（{ok, message, user}）、auth_email_code（{stage: captcha|sent|failed}）、formlm_generate（{ok, appId, planType, tasks[]}）、formlm_execute（{ok, taskStatus, shareToken, shareUrl, builderUrl, dataUrl, accessType}）和 formlm_exec（{ok, code, message, data}）。批处理调用方和目录质量扫描器可以依赖字段，而不必解析说明文字。

---

v0.5.3 新增内容

提升 MCP 目录的工具元数据质量，并让 Agent 使用体验更安全：

• 全部 10 个 MCP 工具现在都提供标准 annotations（只读／破坏性／幂等／开放世界提示）和易于理解的 title — 支持这些功能的客户端可在执行前显示风险徽章和友好标签（formlm_exec 明确标记为具有破坏性；formlm_doctor/formlm_snapshot 标记为只读）。
• 五个只读工具返回经过校验的结构化输出：auth_status、formlm_usage、formlm_snapshot、formlm_doctor 和 formlm_skill 现在都声明了 outputSchema，并在面向用户的文本之外提供可供机器校验的 structuredContent — 批处理审计工具可以直接读取字段，而不必解析说明文字（例如 doctor.findings[].fix、snapshot.data._degraded、usage.appsLeft）。
• 上方的工具表现在列出了全部 10 个工具 — 自添加 formlm_usage 以来，表格一直停留在 9 个。

---

v0.5.0 新增内容

根据真实 Agent 的实地反馈（对 50 个应用进行批量运行）开展的加固工作，并进行了第二轮复核，将每项反馈与代码逐一核对，并通过机器验证所有文档中的命令。

• share publish 现在默认允许匿名访问（--access visitor），并提供 --access / --perm / --days / --no-style；新增的 share set 子命令会原样传递服务端参数，因此“任何人 + 永久有效”不再需要调用内部 API。此前，publish 被硬编码为 form-type all，这要求登录——匿名填写者会看到登录页面。

• expert config --enable 不再自我破坏：现在会以空格分隔的形式传递值（--enable true），服务端也能再次接受它。此前，--enable=true 会被当作未知选项拒绝，整个命令会被丢弃，但返回的结果仍报告成功。

• 参数错误不再被报告为成功：picocli 的验证失败现在会映射为 code != 0 / ok:false，而不是把错误文本藏在 data 中并返回 code:0。

• 机器输出统一：snapshot 和 auth status 现在也会遵循 --json/FORMLM_JSON=1，并使用与其他命令相同的 {ok,code,message,data} 结果封装；面向用户的指导信息已移至 stderr，因此 stdout 只有一行可解析内容。

• app remove 现在是 app delete 的真正别名；app list 新增了 --all / --limit / --page / --with-urls；app urls 会返回 shareToken、published、shareType/Perm/Day 和绝对 https URL。

• 新增 doctor 命令（以及 MCP formlm_doctor 工具）：每个应用执行一次只读检查，涵盖评分覆盖情况、无效/空的专家、样式、意外的证书页面、语言一致性（--expect-lang、--deep 扫描小组件文本），以及分享访问权限和可达性。

• 新增 snapshot --summary 紧凑审计配置（计数、维度名称、报告页面、专家标记、分享类型/权限/天数 + shareToken）——批量验证不再需要解析完整的模块载荷。

• 计划缓存过期后可继续执行：使用 smart plan --save-plan <file> + smart execute --plan-file <file>（服务端计划缓存有效期约为 10 分钟，文档现在也已注明）。

• 重试/退避：只读命令遇到 408/429/5xx 时会采用指数退避进行重试；写入操作绝不会自动重试。可通过 FORMLM_RETRIES / FORMLM_TIMEOUT_MS 调整。

• report page remove --name "结业证书" 会在服务端解析页面名称；report page update 会验证页面是否存在（使用 --upsert 可选择启用更新或插入）；写入确认信息更精简；widget remove 现在会持久化（此前它返回成功但没有保存）。

• 现在已有 smart generate，它是一个保留可恢复能力的封装，依次执行 plan → execute×N → (--publish) → (--doctor)，README 终于与命令列表保持一致。早期版本曾记录一个从未实现的 smart generate 命令（每个 Agent 首先运行的命令，而它当时会失败）。

• 生成结果现在可以固定：smart plan --dimensions "A|B|C" 可固定评分维度的名称和数量，--app-name 可固定应用显示名称，--dry-run 可验证提示词而不留下残留应用。此前，未固定的维度会被 AI 重命名或重新计数，迫使页面与应用返工（批量测量：11/13 个页面）。

• 现在会通过机器验证文档是否与命令列表一致：README/INSTALL 中的每个 formlm-cli … 示例都会执行，并检查是否有未知/缺失选项（149 个示例，0 处偏差），因此文档中的命令不会再悄然出现偏差。

• smart plan 输出现在包含结构化的 modules / missingModules，调用方无需解析说明文字即可检测覆盖缺口（例如，非咨询类计划中没有 expert）；原始 exec 403 现在会列出允许使用的命令集合。

---

v0.2.1 新增内容

• Field ID 验证：field add --id 现在会强制匹配 snake_case 正则表达式（^[a-zA-Z0-9_]+$）
• Snapshot --md 标志：默认统一输出 JSON，也可选择使用 --md 输出 Markdown 格式
• 错误处理程序：缺少必需选项时，现在会打印用法提示，而不只是输出错误消息
• 服务端修复：SessionContext appId 同步、移除 ScaleCommand B5 反转、CLI --app 提取

---

v0.2.0 新增内容

MCP 架构已从头到尾彻底重新设计：

• 34 个扁平工具 → 6 个分层工具 + 6 个知识资源
• 智能层：formlm_generate 封装服务端的 AssessAgent 流程
• 领域知识：6 个 MCP 资源直接向 AI Agent 提供 SKILL.md 文件
• 状态感知：formlm_snapshot 一次调用即可汇总所有模块状态
• P0 约束：直接嵌入命令描述中 — AI 每次都会看到

架构

┌─────────────────────────────────────────────────────────┐
│         AI Agent (any MCP Client: Claude / Cursor /       │
│           Codex CLI / Windsurf / Cline / ...)             │
├─────────────────────────────────────────────────────────┤
│  Tier 0: auth_login, auth_email_code, auth_status      │
│  Tier 1: formlm_generate                   ← Smart Pipeline │
│  Tier 2: formlm_snapshot, formlm_skill ← State + Knowledge│
│  Tier 3: formlm_exec                    ← Direct Commands │
├─────────────────────────────────────────────────────────┤
│  Resources: formlm://skills/{form,scale,connect,        │
│              report,expert,share}                        │
├─────────────────────────────────────────────────────────┤
│               formlm-cli MCP Server                      │
├─────────────────────────────────────────────────────────┤
│            FormLM Server (McpV1Api)                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│  │AssessAgent│ │BuilderAgent│ │CliService│ │SKILL.md  │    │
│  │ (Plan+   │ │ (Think+  │ │ (picocli │ │ (domain  │    │
│  │  Execute) │ │  Reflect)│ │  dispatch)│ │  rules)  │    │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
└─────────────────────────────────────────────────────────┘

---

安装

npm install -g @formlm/cli

需要 Node.js ≥ 18。

详细的分步指南（包括 Claude Desktop / Cursor / Codex CLI / Windsurf / Cline 的 MCP 配置），请参阅 INSTALL.md。

---

快速开始

1. 登录

# Recommended: copy your Access Token from the web app
# (formlm.me → sign in → Workspace → top-right user menu → Account Settings → Access Token → Copy)
formlm-cli auth login --token <your-token>

# Interactive login — pick one of three methods:
#   1) Access Token    (same as above)
#   2) Email verification code  (no password, no browser — fully in the terminal)
#   3) Email + password (only if your account has set a password —
#      email-verification-code and Google accounts have none)
#
# New here without an account? Pick method 2 — the first email-code login
# registers the account automatically (with free AI credits); no website visit needed.
formlm-cli auth login

# Check your remaining budget BEFORE batch work — plan, app slots (free plan: 10 apps,
# recycle-bin apps still hold a slot) and AI credits:
formlm-cli usage

2. 智能流程（AI 推荐）

创建采用两阶段流程（每个模块依次执行 plan → execute）。如果不需要逐模块控制，smart generate 是对相同步骤的一次性封装：

# One-shot: plan → execute every module → publish anonymously → quality audit
formlm-cli smart generate \
  --input "Create a workplace stress assessment with 10 questions, 3 dimensions (workload, autonomy, support), and detailed score interpretations" \
  --plan-type assessment --question-count 10-15 --lang en --publish --doctor

也可以逐步执行（批量操作推荐此方式 — 每个步骤都可恢复）：

# Phase 1 — plan (~10-30s): creates the app and returns appId + task list.
# --save-plan keeps the full plan JSON on disk so modules can still be executed
# after the server-side plan cache (~10 min) expires.
formlm-cli smart plan --input "Create a workplace stress assessment with 10 questions, 3 dimensions, and detailed score interpretations" \
  --plan-type assessment --question-count 10-15 --lang en --dimensions "Workload|Autonomy|Support" --save-plan plan.json

# Phase 2 — execute every module listed by the plan, in order (~30-120s each):
formlm-cli smart execute --app <appId> --module form
formlm-cli smart execute --app <appId> --module scale
formlm-cli smart execute --app <appId> --module connect
formlm-cli smart execute --app <appId> --module report
formlm-cli smart execute --app <appId> --module share

# Publish so anonymous visitors can fill it in (each respondent submits once, permanent):
formlm-cli share publish --app <appId>            # --access visitor is the default
#   ⚠️ an un-styled app auto-gets a default style here (30-120s AI) — pass --no-style to skip

# Verify quality in one read-only call (see Doctor below):
formlm-cli doctor --app <appId> --expect-lang en

⚠️ 模块覆盖范围取决于 planType。 只有 consultation 计划包含 expert 任务； assessment / exam / report / survey / learn 不包含该任务。缺少模块时，smart plan 会打印警告 — 请使用 formlm-cli expert config --app <appId> --name ... --role ... --kbText ... 显式添加 expert。

⚠️ 样式： 流程中的 connect 模块负责应用视觉样式。如果跳过流程，改用直接命令，则必须运行 connect style apply-all，否则表单会保持未设置样式的朴素外观。

3. 获取所有应用 URL（创建后）

# Get fill-in, editor, data management, and Data API URLs in one call
formlm-cli app urls --app <appId>
# Returns: shareUrl (relative /s/<token>), shareUrlAbsolute (https, iframe-ready),
#          shareToken, published, shareType/sharePerm/shareDay,
#          builderUrl (editor), dataUrl (data management),
#          apiUrl + apiHelpUrl (Data API, empty until enabled)

4. 启用数据 API（适用于任何页面的表单后端）

# Turn a form into a data endpoint — static sites, local pages, and AI apps
# can POST submissions straight to it (CORS enabled, no server needed)
formlm-cli share api --app <appId> --submit true --query true
# Then point your HTML form / fetch / curl at the returned endpoint.
# Append ?help to the endpoint for its Markdown docs (readable by AI agents).

5. 美化表单（使用直接命令时）

# Apply AI-generated visual style to all pages (takes 30-120s)
formlm-cli connect style apply-all --app <appId> --look "职场压力评估，深蓝专业风格" --theme minimalist

6. 直接命令（用于精细控制）

# Get a snapshot of all module states
formlm-cli snapshot --app <appId>
formlm-cli snapshot --app <appId> --md              # Markdown format (token-efficient for AI)
formlm-cli snapshot --app <appId> --summary          # compact audit profile (batch verification)
formlm-cli snapshot --app <appId> --with-values      # include report widget body text

# Read a skill document before constructing commands
formlm-cli skill form
formlm-cli skill scale

# Scale commands
formlm-cli scale query --app <appId>
formlm-cli scale add --app <appId> --id stress --name "Stress Level" --format sum --kbText "..."
formlm-cli scale keys add --app <appId> --scale stress --fields q1,q2,q3
formlm-cli scale data add --app <appId> --scale stress --bands "Low:desc||Moderate:desc||High:desc"   # recommended: server auto-computes even boundaries + 999 sentinel

# Report commands
formlm-cli report query --app <appId>
formlm-cli report page add --app <appId> --name "Summary"                     # page type defaults to A4
formlm-cli report widget add --app <appId> --page <pageId> --type scale-chart --format bar --scaleId <dim> --x 0 --y 0 --w 24 --h 12
formlm-cli report widget logic add --app <appId> --page <pageId> --id <widgetId> --min 0 --max 20 --content "<p>Keep it up</p>"

# Expert commands (--name and --kbText are required by the server)
formlm-cli expert query --app <appId>
formlm-cli expert config --app <appId> --name "Career Coach" --role "资深职业规划师" --kbText "..." --theme Warm
formlm-cli expert set --app <appId> --property enable --value true   # single-property toggle

# Quality audit (read-only)
formlm-cli doctor --app <appId>
formlm-cli doctor --app <appId> --expect-lang en --deep

7. 用作 MCP 服务

formlm-cli mcp

这会启动 MCP 服务（stdio 传输），包含 10 个工具 + 6 个资源，可供 AI Agent 连接。

---

命令参考

智能流程（AI 推荐）

有两种使用方式：smart plan + smart execute（显式、可恢复 — 推荐用于批量操作），或使用 smart generate，它是对上述步骤的轻量封装：

# Phase 1 — plan only (creates the app, returns appId + tasks; cached server-side ~10min)
formlm-cli smart plan --input "..." [--plan-type assessment] [--style "温暖亲切"] [--question-count 10-15] \
  [--lang en] [--dimensions "Focus|Sleep|Load"] [--app-name "Team Focus Check"] \
  [--save-plan plan.json] [--dry-run]

# Phase 2 — execute one module at a time (form / scale / connect / report / expert / share)
formlm-cli smart execute --app <appId> --module form
formlm-cli smart execute --app <appId> --module scale --plan-file plan.json   # after the cache expired
formlm-cli smart execute --app <appId> --module scale --clear-first          # re-run without duplicating dimensions

# One-shot wrapper — plan → execute every module → optional publish → optional doctor
formlm-cli smart generate --input "..." --plan-type assessment --lang en --publish --doctor
formlm-cli smart generate --input "..." --only form,scale,report       # partial build
formlm-cli smart generate --input "..." --skip connect                 # leave styling out

固定与即兴。 默认情况下，Plan AI 会自行生成维度名称、数量和应用名称，这会导致批量运行时页面与应用不一致。使用 --dimensions 固定维度列表（确切的名称和数量），使用 --app-name 固定显示名称；之后使用 snapshot --summary 验证（它会报告 dimNames）。

--dry-run 会验证提示词/规范，并删除探测用应用（服务器在规划时总会创建应用），因此试验不会留下任何残留。

成功状态可供机器读取：smart execute 会返回 data.taskStatus（success / error），而 smart generate 会返回 {appId, modules:[{module,status,error}], publish, doctor, resumeHint} — 应以这些字段为准，而非面向用户的文字说明。如果运行中途失败，应用会保留，resumeHint 会提供准确的恢复命令。

快照

# Get all module states in one call (JSON by default)
formlm-cli snapshot --app <appId>
formlm-cli snapshot --app <appId> --module scale    # Only scale module
formlm-cli snapshot --app <appId> --md             # Markdown format (token-efficient for AI)
formlm-cli snapshot --app <appId> --summary        # Compact audit profile (counts/dim names/report pages/expert/share + shareToken)
formlm-cli snapshot --app <appId> --with-values    # + report widget body text (per-page queries)
formlm-cli snapshot --apps <id1,id2,...> --summary # Batch: N apps in ONE process (connection reuse, FORMLM_CONCURRENCY parallel apps, default 4)

实测：单个进程在约 13 秒内完成 5 个应用 × 7 次模块查询，共 35 个请求；相比之下，此前每个应用都要启动一个全新的 Node 进程（旧的串行子进程模式大约耗时 5 倍，而且无法复用连接）。

snapshot 是由客户端合成的：它会并行调用 6 条 assess <module> query 命令。服务端没有 assess snapshot，因此按设计，通过原始 POST /api/v1/mcp/exec 调用该命令会返回 403——需要在 HTTP 侧批处理时，请自行循环调用这 6 条查询。如果某个模块获取失败，结果会包含 _errors / _degraded（应将其视为未知，而非“空模块”）。

Doctor（只读质量审计）

# One call per app: content/scoring coverage, expert sanity, styling,
# unexpected certificate pages, share access semantics, link reachability
formlm-cli doctor --app <appId>

# Whole batch in one process (aggregate envelope; exit 1 if any app fails)
formlm-cli doctor --apps <id1,id2,...> --expect-lang en

# Add the language-consistency scan (classic batch defect: English app shipped with Chinese boilerplate)
formlm-cli doctor --app <appId> --expect-lang en            # titles/labels
formlm-cli doctor --app <appId> --expect-lang zh-hant --deep  # also scan report widget body text
formlm-cli doctor --app <appId> --no-probe                  # skip the fill-in URL reachability probe

输出采用标准信封格式；存在 fail 级别的问题时，返回 ok:false 和退出码 1，便于批处理驱动据此进行拦截。每个问题都附带可直接运行的 fix 命令。此命令为只读，不会写入任何内容。

技能文档

# Get SKILL.md domain knowledge (P0/P1/P2 constraints, command templates)
formlm-cli skill form       # Form field rules
formlm-cli skill scale      # Scale dimension rules
formlm-cli skill connect    # Page styling rules
formlm-cli skill report     # Report layout rules
formlm-cli skill expert     # Expert interpretation rules
formlm-cli skill share      # Share/publish rules

身份验证

formlm-cli auth login --token <tok>   # Login with Access Token (recommended: formlm.me → Account Settings)
formlm-cli auth login                 # Interactive login — 1) Access Token, 2) email verification code (no password needed), 3) email + password
formlm-cli auth status                # Check current login state (tokens expire after 7 days)
formlm-cli auth logout                # Clear local token

用量（配额与额度）

formlm-cli usage                      # plan / app slots (in-use + recycle bin) / AI credits
FORMLM_JSON=1 formlm-cli usage        # {account,plan,appsUsed,appLimit,appsRemaining,unlimited,credits,...}

批量操作前，请先检查剩余预算：免费套餐最多支持 10 个应用（达到上限后会返回 403 app-limit——回收站中的应用仍占用名额，清除后才能释放）；每次成功完成的智能生成约消耗 20 个额度（额度最低为零，不会阻止生成）。在较旧的服务端上，用量/额度信息会显示为 n/a——命令不会猜测无法读取的数字。

配置文件（多账户）

formlm-cli profile add --name work --url https://formlm.me --token <tok>
formlm-cli profile list
formlm-cli profile use work           # Switch default profile
formlm-cli --profile work app list    # Use a profile for one command

应用

formlm-cli app list                                               # first page (latest 20)
formlm-cli app list --all                                          # full inventory (server page size capped at 500)
formlm-cli app list --limit 100 --page 2                           # explicit paging
formlm-cli app list --all --with-urls                              # + published/shareType/sharePerm/shareDay/shareUrl/shareToken per app
formlm-cli app list --name "wellness"                              # filter by app name
formlm-cli app create --name "My Form" --description "..."
formlm-cli app get --app <appId>
formlm-cli app update --app <appId> --name "New Name" --theme blue
formlm-cli app delete --app <appId>                                # Delete an app (irreversible)
formlm-cli app remove --app <appId>                                # alias of app delete
formlm-cli app urls --app <appId>                                  # Get fill-in / editor / data URLs + shareToken

字段

formlm-cli field schema                                         # All supported field types
formlm-cli field config --type radio                            # Configurable props for a type
formlm-cli field list --app <appId>
formlm-cli field find --app <appId> --id q1                     # Get a single field
formlm-cli field add --app <appId> --id q1 --name "Name" --type input --required
formlm-cli field update --app <appId> --id q1 --title "Your Full Name"
formlm-cli field remove --app <appId> --id q1
formlm-cli field set-property --app <appId> --id q1 --property options.0.score --value 5

量表（维度与评分）

formlm-cli scale query --app <appId>                          # List all dimensions
formlm-cli scale find --app <appId> --id <scaleId>            # Find a dimension
formlm-cli scale add --app <appId> --id stress --name "Stress" --format sum --kbText "..."
formlm-cli scale update --app <appId> --id stress --name "Stress Level"
formlm-cli scale set --app <appId> --id stress --property direction --value negative
formlm-cli scale remove --app <appId> --id stress
formlm-cli scale clear --app <appId>
formlm-cli scale config --app <appId> --enable-single true

# Associate fields with a dimension
formlm-cli scale keys add --app <appId> --scale stress --fields q1,q2,q3 [--polarities "q3:negative"]
formlm-cli scale keys remove --app <appId> --scale stress --fields q1
formlm-cli scale keys list --app <appId> --scale stress
formlm-cli scale keys set --app <appId> --scale stress --fields q3 --negScore true

# Configure score ranges
formlm-cli scale data add --app <appId> --scale stress --bands "Low:desc||Moderate:desc||High:desc"   # recommended: server auto-computes even boundaries + 999 sentinel (ordered lowest→highest score)
formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:High"                   # manual boundaries; only for non-even knowledge-specified thresholds
formlm-cli scale data update --app <appId> --scale stress --id <dataId> --value "Moderate"
formlm-cli scale data remove --app <appId> --scale stress --id <dataId>
formlm-cli scale data list --app <appId> --scale stress
formlm-cli scale data clear --app <appId> --scale stress

连接（页面样式与视觉设计）

formlm-cli connect query --app <appId> [--type cover|main|final] [--filter <keyword>] --md
formlm-cli connect find --app <appId> --filter <keyword>
formlm-cli connect types [--category cover|main|final] --verbose
formlm-cli connect config --category cover --format rich-text

# Cover page management
formlm-cli connect cover-page add --app <appId> --id cover_main --name "Welcome" --format rich-text --value "<h1>Hello</h1>"
formlm-cli connect cover-page update --app <appId> --id cover_main --name "New Title"
formlm-cli connect cover-page find --app <appId> [--id cover_main]
formlm-cli connect cover-page remove --app <appId> [--id cover_main]

# Final page management
formlm-cli connect final-page add --app <appId> --id final_report --name "Thank You" --enable-report true
formlm-cli connect final-page update --app <appId> --id final_report --name "Done"
formlm-cli connect final-page find --app <appId> [--id final_report]
formlm-cli connect final-page remove --app <appId> [--id final_report]

# Main page management
formlm-cli connect main-page set --app <appId> --format card
formlm-cli connect main-page set --app <appId> --field X1 --description "<p>Context</p>"

# Visual style
formlm-cli connect style set --app <appId> --type cover --bg "#f3f3fe" --fg "#ffffff" --font "#01105c"
formlm-cli connect style query --app <appId> --type cover
formlm-cli connect style apply --app <appId> --look "deep blue tech, frosted glass cards" [--theme Minimal] [--layout flat]
formlm-cli connect style apply-all --app <appId> --look "light warm Japanese style" [--theme Minimal] [--layout flat]
formlm-cli connect style move --app <appId> --id <pageId> --direction up

报告（页面与组件）

formlm-cli report query --app <appId>                           # List all report pages
formlm-cli report find --app <appId> --filter <keyword>         # Find report widget

# Note: update goes through the explicit owners — `report page update` (page name/bg/style/svg)
# and `report widget update` (widget props). The server also accepts the merged
# `assess report update --page <pageId> [--id <widgetId>]` form on the raw exec channel.

# Page management (a page is a 48-col × 68-row grid canvas; layout comes from widget x/y/w/h, not a page flag)
formlm-cli report page add --app <appId> --name "Summary" [--type A4]
formlm-cli report page update --app <appId> --id <pageId> --name "Overview"      # fails if the id does not exist
formlm-cli report page update --app <appId> --id <pageId> --name "Overview" --upsert   # opt into the server upsert (creates a blank page)
formlm-cli report page remove --app <appId> --id <pageId>
formlm-cli report page remove --app <appId> --name "结业证书"                       # locate by human-readable name

# Widget management (every widget command needs --page; set/find/update/remove also need --id)
formlm-cli report widget list --app <appId> --page <pageId>
formlm-cli report widget find --app <appId> --page <pageId> --id <widgetId>          # full detail incl. HTML value
formlm-cli report widget set --app <appId> --page <pageId> --id <widgetId> --property value --value "{{TotalScore}}"
formlm-cli report widget add --app <appId> --page <pageId> --type scale-chart --format bar --scaleId <dim> --x 0 --y 0 --w 24 --h 12
formlm-cli report widget update --app <appId> --page <pageId> --id <widgetId> --name "Updated Chart"
formlm-cli report widget remove --app <appId> --page <pageId> --id <widgetId>
formlm-cli report widget types --verbose                                             # all widget types (+ descriptions)
formlm-cli report widget config --type scale-chart                                   # configurable properties of one type

# Conditional display rules (logic lives UNDER widget)
formlm-cli report widget logic add --app <appId> --page <pageId> --id <widgetId> --min 0 --max 20 --content "<p>Low band text</p>"
formlm-cli report widget logic list --app <appId> --page <pageId> --id <widgetId>
formlm-cli report widget logic remove --app <appId> --page <pageId> --id <widgetId> --logicId <logicId>

专家（AI 解读）

formlm-cli expert query --app <appId>                    # Query expert config (--md for a compact table)
formlm-cli expert find --app <appId>                     # Full config incl. prompt/welcome text
formlm-cli expert config --app <appId> --name "Dr. AI" --role "Career coach" \
  --kbText "..." [--welcome ...] [--question1 ...] [--theme Warm] [--enable true]   # create/update (name + kbText required)
formlm-cli expert set --app <appId> --property enable --value true    # single-property toggle;
                                                                        # properties: name/role/description/style/welcome/
                                                                        # prompt/question1..3/kbText/enable/enableWelcome/theme
formlm-cli expert avatar --app <appId> --url <url> --enable true      # needs an existing expert (config first)
formlm-cli expert remove --app <appId>
formlm-cli expert chat --app <appId> --input "Explain my score"

布尔标志以空格分隔的形式转发（--enable true），绝不使用 --enable=true——服务端通过 picocli arity 0..1 解析这些参数。expert config 默认启用 Agent；传入 --enable false 可在配置时保持其关闭。

分享（发布与访问）

# Access types (know these — "public" is ambiguous):
#   visitor = anonymous, no login required  → "anyone can fill" (the usual public form)
#   all     = every LOGGED-IN FormLM user   → anonymous visitors hit the login page
#   secret  = password-protected   |   owner = creator only   |   no = unpublish
formlm-cli share publish --app <appId>                      # anonymous (visitor) + one submission + permanent
formlm-cli share publish --app <appId> --access all --perm 2 --days 14    # explicit control
formlm-cli share publish --app <appId> --no-style            # skip the automatic style fallback
formlm-cli share set --app <appId> --type visitor --perm 1 --day 0        # raw server parameters (idempotent)
formlm-cli share unpublish --app <appId>
formlm-cli share query --app <appId>                        # authoritative type/perm/day triple
formlm-cli share verify --app <appId>                       # published + anonymous + permanent + reachability in one call
formlm-cli share url --app <appId>                          # URLs incl. shareToken
formlm-cli share api --app <appId>                          # Configure the Data API (form backend endpoint)
formlm-cli share api --app <appId> --submit true --query true --auto-create true

有效期规则（服务端）： 只有 --days 1..30 会被视为有限期限；0、forever 或任何大于 30 的值都会规范化为永久有效（哨兵值 3650000）。此渠道不支持 90 天或 1 年的发布期限。

验证“任何人都能访问”： curl 请求分享 URL 返回 200 并不能证明任何事——即使有登录门槛，SPA 外壳仍会返回 200。请使用 share verify（或读取 share query 返回的类型/权限/天数三元组）。

smart execute --module share 与 share publish 的区别： 流程中的分享模块会应用方案的发布设置；share publish 是显式且幂等的 CLI 入口，它还会确保使用匿名访问和永久有效的默认设置，并输出最终 URL/shareToken。重复运行 share publish 是安全的。如果你从未为应用设置样式，发布时会先自动应用默认样式（AI 生成需要 30-120 秒）——传入 --no-style 可跳过此步骤。

Data API 可将表单转换为 HTTP 数据端点：向端点发送 POST JSON（或使用 /form 路径提交原生 HTML 表单），通过查询端点读取记录，并将 ?help URL 提供给 AI Agent，让它自行发现 API。

---

MCP 集成

FormLM CLI 可通过 stdio 作为标准 MCP Server 使用，并可接入任何兼容 MCP 的 AI 平台——Claude Desktop、Cursor、Codex CLI、Windsurf、Cline 等。

⚠️ macOS/Linux 用户： 桌面 AI 客户端启动 MCP 服务时，通常不会使用完整的终端 PATH，这可能导致出现 command not found 错误。请参阅 INSTALL.md → 第 4 步，了解 env.PATH 修复方法、各平台的配置文件位置（包括 Codex CLI 的 TOML 格式）以及完整设置指南。

没有令牌？没问题。 如果省略 FORMLM_TOKEN，AI 会提示你通过 auth_login 工具进行身份验证——粘贴 Access Token（从 formlm.me → Workspace → Account Settings 获取；推荐），通过 auth_email_code 在聊天中完成电子邮件验证码登录（无需浏览器），或直接在聊天中使用电子邮件和密码登录。

可用的 MCP 工具（10 个）

等级	工具	描述
0	auth_login	使用访问令牌（推荐）、电子邮件验证码或电子邮件 + 密码登录
0	auth_email_code	通过电子邮件验证码登录——获取验证码图片并发送验证码（全程在聊天中完成）
0	auth_status	检查当前登录状态
0	formlm_usage	一览账户额度：套餐、应用槽位使用情况、AI 积分——批量创建前请先检查
1	formlm_generate	生成执行计划（阶段 1：创建应用并返回 appId + 任务）
1	formlm_execute	在 formlm_generate 之后逐个执行计划模块
2	formlm_doctor	对单个应用进行只读质量审计（评分覆盖率、无效专家、样式、证书页面、语言一致性、分享访问权限、可访问性）
2	formlm_snapshot	汇总所有模块的状态；summary: true 会返回精简的审计概况
2	formlm_skill	获取技能模块的领域知识 SKILL.md
3	formlm_exec	直接执行任何已列入白名单的 CLI 命令

可用的 MCP 资源（6 个）

资源 URI	描述
formlm://skills/form	表单字段 SKILL.md——P0 约束、字段类型、评分规则
formlm://skills/scale	量表维度 SKILL.md——范围规则、极性、方向
formlm://skills/connect	连接页面 SKILL.md——主题模式、布局格式
formlm://skills/report	报告布局 SKILL.md——组件类型、变量、逻辑
formlm://skills/expert	专家解读 SKILL.md——AI 配置、聊天规则
formlm://skills/share	分享/发布 SKILL.md——访问类型、幂等性

---

环境变量

变量	描述
FORMLM_BASE_URL	FormLM 服务 URL（默认值：https://formlm.me）
FORMLM_TOKEN	你的身份验证令牌（可替代 auth login；避免机密信息进入 shell 历史记录）
FORMLM_JSON=1	机器可读输出：每条命令都会在标准输出中打印一行可解析内容 {ok,code,message,data}（等同于全局 --json 标志）
FORMLM_NO_EXIT=1	批处理安全：失败时绝不调用 process.exit()——错误命令不会终止驱动程序循环（错误会通过 ok:false 信封或抛出的错误呈现）
FORMLM_TIMEOUT_MS	每条命令的默认请求超时时间（毫秒，默认值：60000）
FORMLM_TIMEOUT_PLAN / FORMLM_TIMEOUT_EXECUTE / FORMLM_TIMEOUT_STYLE	覆盖智能计划（120s）、智能执行（300s）和样式（600s）的超时时间
FORMLM_RETRIES	瞬时故障时的最大尝试次数（默认值：3）。只读命令会在出现 408/429/5xx 时重试；写入操作绝不会自动重试
FORMLM_CONCURRENCY	批处理命令（snapshot --apps、doctor --apps）的进程内并行度，默认值：4

---

脚本与批量使用

# One parseable line per command; guidance/hints go to stderr, stdout stays clean:
FORMLM_JSON=1 FORMLM_NO_EXIT=1 formlm-cli snapshot --app <appId> --summary
FORMLM_JSON=1 formlm-cli share verify --app <appId>        # {ok, data:{type,forever,anonymous,httpStatus,shareToken}}
FORMLM_JSON=1 formlm-cli doctor  --app <appId> --expect-lang en   # ok:false when a fail-level finding exists

# Whole batch in one process (no per-app Node cold start; tunable with FORMLM_CONCURRENCY):
FORMLM_JSON=1 formlm-cli doctor   --apps id1,id2,id3 --expect-lang en
FORMLM_JSON=1 formlm-cli snapshot --apps id1,id2,id3 --summary

信封：{ "ok": bool, "code": int, "message": string, "data": object|null }——data 始终已解析（无需二次解码），验证/参数错误现在会返回非零 code，而不是将错误文本隐藏在 data 中却报告成功。

状态码

代码	含义	处理方式
0	成功	—
207	部分成功（多模块读取时，其中一个模块失败）	结果包含 _errors/_degraded；请重新检查该模块，不要假定它为空
400	请求错误／参数或校验错误	查看 message；服务会回显 picocli 的提示（有效值、缺少的选项）
401	未通过身份验证——缺少令牌或令牌已过期（有效期为 7 天）	formlm-cli auth login（方法 1 或 2）／--token-stdin／设置 FORMLM_TOKEN
403	命令不在 exec 白名单中 · 凭据／验证码错误 · 已达到免费套餐的应用数量上限（消息以 app-limit: 开头）	查看下方的白名单及配额与限制；app-limit → 删除未使用的应用（同时清空回收站），或升级
408	客户端请求超时	只读操作可重试；对于 smart execute，请重新运行该模块（写入操作不会自动重试）
429	请求频率受限——登录尝试、发送验证码配额、AI 命令（message 以 rate-limit: 开头）	等待后采用退避策略重试；批处理流程应低于下方的 AI 限制
500	传输失败或服务错误	只读命令会自动重试

配额与限制（由服务端强制执行）

限制	数值	达到限制时的行为
每个免费套餐账户的应用数量	10（回收站中的应用仍占用名额——清空回收站以释放名额）	app create／smart plan 返回 403，且消息中包含 app-limit:；前往 formlm.me → Workspace → #/vip 升级
每个账户的 AI 命令数量	60 段/分钟（smart plan／smart execute／expert chat；一次完整的 smart generate ≈ 7 段）	返回 429，且包含 rate-limit:；降低请求频率，或使用 FORMLM_CONCURRENCY ≤ 4
每个生成应用的 AI 积分	完成智能生成后，待所有模块运行完毕即计为一次扣费（≈ 20 积分）；新账户初始约有 100 个免费积分	扣减最多为零，且绝不会阻止生成（与 Web 应用行为一致）
Expert chat 使用量	每个应用的每日计算预算 + 每个账户的每日对话轮数上限	被拒绝时，消息中会包含 round-limit:；请于次日重试

原始 POST /api/v1/mcp/exec 白名单

exec 通道仅接受 3 个令牌的命令路径（assess <module> <action>）。其他命令都会返回 403 not allowed via MCP，这是设计如此——特别是，服务端不存在 assess snapshot 和 assess field … （它们是客户端包装器），因此批量 HTTP 调用方必须调用底层查询：

assess app      list | create | use | current | update | remove | urls
assess form     query | find | types | config | add | update | remove | move | set-property
assess scale    query | find | add | update | set | remove | clear | config | keys | data
assess connect  query | find | types | config | cover-page | final-page | main-page | style
assess report   query | find | update | page | widget        (conditional logic is `report widget logic …`)
assess expert   query | find | config | set | avatar | remove | chat
assess share    set | query | url | api | flavor
assess smart    plan | execute
assess skill    form | scale | connect | report | expert | share

吞吐量说明

• 每次 CLI 调用都会启动一个新的 Node 进程并发起独立的 HTTP 调用；对于大型批次，应并发处理互不依赖的 应用（服务可承受适度并行），而不要串行处理。
• snapshot/doctor 会并行查询各模块；使用 --module / --summary 可缩小载荷。
• 服务较慢？请调高 FORMLM_TIMEOUT_MS 和 FORMLM_RETRIES，而不要手动编写重试循环。
• 在一个进程内批量处理多个应用：使用 snapshot --apps … / doctor --apps …，或直接导入构建好的 模块（import { execCommand } from '@formlm/cli/dist/exec.js'）并循环调用——HTTP 连接会复用，且不会为每个应用单独冷启动 Node。

版本耦合（CLI ↔ 服务端）

某些命令依赖与其同时添加的服务端选项；如果使用较旧的服务端，就会出现明显的 400 Unknown option … 错误（多亏了防止虚假成功的保护机制，不会静默成功）：

需要服务端支持	命令 / 标志
✔	app list --all / --limit / --page / --with-urls
✔	app urls 原生支持 shareToken + published/shareType/…（CLI 会在回退时从 shareUrl 填入 shareToken）
✔	report page remove --name "…"（名称到 ID 的解析移至服务端，因此直接执行也能受益）
✔	expert config --enable true|false（旧版服务端上回退为 expert set --property enable）
✔	smart plan --dimensions / --app-name、smart execute --plan-file（--plan-b64 传输方式）
✔	usage / MCP formlm_usage 字段（GET /api/v1/mcp/auth/me 上的 tenantType/credit/appUsage/appLimit）——旧版服务端会降级为 n/a

---

链接

• 网站：https://formlm.me
• 平台：在 formlm.me 注册并开始构建
• GitHub：https://github.com/formlm/cli
• npm：https://www.npmjs.com/package/@formlm/cli
• Smithery：https://smithery.ai/servers/formlm/cli

---

联系方式

有疑问、反馈，或需要入门帮助吗？

📧 [email protected]

欢迎随时联系我们——我们很乐意提供帮助。

---

许可证

MIT © FormLM