FormLM

formlm-cli

FormLM の公式 CLI および MCP サーバーです。AI エージェントがフォームを直接作成・管理できます。

キーワード：FormLM CLI、MCP サーバー、AI エージェント向けフォームビルダー、フォームの自動化、アセスメントプラットフォーム CLI、Claude MCP、Cursor MCP、AI を活用したフォーム、formlm-cli、npm CLI ツール

---

FormLM とは？

FormLM は、AI を活用したフォームおよびアセスメントプラットフォームです。自然言語による指示だけで、スマートフォーム、採点クイズ、専門的な評価レポートを作成できます。

formlm-cli を使えば、ターミナルから FormLM を直接操作したり、任意の AI エージェント（Claude、Cursor、GPT など）に MCP サーバーとして接続したりできます。UI は不要です。

公式ウェブサイトはこちら：https://formlm.me

formlm-cli は me.formlm/cli として 公式 MCP Registry に登録されています。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 ディレクトリのツールメタデータ品質を向上させ、エージェントの操作をより安全にしました。

• 10 個すべての MCP ツールが標準の annotations（読み取り専用／破壊的／冪等／オープンワールドのヒント）と、人が読みやすい title を公開します。対応クライアントでは、実行前にリスクバッジやわかりやすいラベルを表示できます（formlm_exec は破壊的操作として明示され、formlm_doctor／formlm_snapshot は読み取り専用です）。
• 5 つの読み取り専用ツールが、検証済みの構造化出力を返します。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 の新機能

実際のエージェントによる現場からの報告（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 にマッピングされるようになり、エラーテキストが code:0 の data 内に隠されることはありません。

• マシン出力を統一しました。snapshot と auth status が --json / FORMLM_JSON=1 に対応し、他のコマンドと同じ {ok,code,message,data} エンベロープを返します。また、ユーザー向けの案内は stderr に移動したため、stdout はパース可能な 1 行のみになります。

• app remove は app delete の正式なエイリアスになりました。app list には --all / --limit / --page / --with-urls が追加され、app urls は shareToken、published、shareType/Perm/Day と絶対 https URL を返します。

• 新しい doctor コマンド（および MCP の formlm_doctor ツール）が追加されました。アプリごとに読み取り専用の呼び出しを 1 回行い、スコアリングの網羅性、無効または空のエキスパート、スタイル、想定外の証明書ページ、言語の一貫性（--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 を指定すると upsert を有効にできます。書き込み確認は簡潔になり、widget remove は変更を保存するようになりました（以前は保存せずに成功を返していました）。

• smart generate が実装されました。plan → execute×N → (--publish) → (--doctor) を実行する、再開可能性を維持したラッパーです。これにより、README の内容がついに実際のコマンドに一致しました。以前のバージョンでは、実装されていない smart generate がドキュメントに記載されていました（エージェントが最初に実行するコマンドで、失敗していました）。

• 生成結果を固定できるようになりました：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 リソースで SKILL.md ファイルを AI エージェントに直接公開します
• 状態認識：formlm_snapshot がすべてのモジュールの状態を 1 回の呼び出しで集約します
• 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 推奨）

作成は2 フェーズのパイプライン（モジュールごとに 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 によって異なります。 expert タスクが含まれるのは consultation プランのみです。assessment / exam / report / survey / learn には含まれません。モジュールが不足している場合、smart plan は警告を表示します。formlm-cli expert config --app <appId> --name ... --role ... --kbText ... を使って、専門家を明示的に追加してください。

⚠️ スタイル設定： パイプラインの 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. Data 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

これにより、10 個のツールと 6 個のリソースを備え、AI エージェントが接続できる MCP サーバー（stdio トランスポート）が起動します。

---

コマンドリファレンス

スマートパイプライン（AI 推奨）

実行方法は 2 通りあります。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)

計測結果：単一プロセスで5つのアプリに対して7つのモジュールクエリを実行し、約13秒で合計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クレジットが消費されます（クレジットは0まで減りますが、生成がブロックされることはありません）。古いサーバーでは、使用状況／クレジットの行は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

Connect（ページのスタイリングとビジュアルデザイン）

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>

Expert（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ではエージェントがデフォルトで有効になります。無効のまま設定するには、--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年間の公開期間は設定できません。

**「誰でもアクセスできる」ことの確認：**共有URLへのcurlが200を返しても、何も証明されません。SPAのシェルはログイン画面の背後でも200を返します。share verifyを使うか、share queryのtype／perm／dayの組み合わせを確認してください。

**smart execute --module shareとshare publishの違い：**パイプラインのshareモジュールはプランの公開設定を適用します。share publishは明示的に実行できる冪等なCLIコマンドで、匿名アクセスと永続公開のデフォルト設定も保証し、最終URLとshareTokenを出力します。share publishは再実行しても安全です。アプリのスタイルを一度も設定していない場合、公開前にデフォルトのスタイルが自動適用されます（AI生成に30～120秒かかります）。これを省略するには--no-styleを渡してください。

Data APIを使うと、フォームをHTTPデータエンドポイントにできます。エンドポイントにPOSTでJSONを送信するか、ネイティブHTMLフォームでは/formパスを使ってください。レコードはクエリエンドポイントから読み取り、?help URLをAIエージェントに渡すと、APIを自動で検出できるようになります。

---

MCP連携

FormLM CLIは標準的なMCPサーバーとしてstdio経由で動作し、MCP互換のあらゆるAIプラットフォーム（Claude Desktop、Cursor、Codex CLI、Windsurf、Clineなど）に接続できます。

**⚠️ macOS/Linuxユーザーの方へ：デスクトップAIクライアントは、完全なターミナルのPATHを引き継がずにMCPサーバーを起動することがよくあり、その場合command not foundエラーが発生することがあります。env.PATHの設定方法、プラットフォームごとの設定ファイルの場所（Codex CLIのTOML形式を含む）、および詳しいセットアップ手順については、INSTALL.md → 手順4**を参照してください。

トークンがなくても大丈夫です。FORMLM_TOKENを省略すると、AIがauth_loginツールを使って認証するよう案内します。Access Token（formlm.me → Workspace → Account Settingsから取得。推奨）を貼り付けるか、チャット内でメールの認証コードを使ってログイン（auth_email_code。ブラウザー不要）するか、チャットでメールアドレスとパスワードを直接入力できます。

利用可能な MCP ツール（10）

Tier	Tool	Description
0	auth_login	アクセストークン（推奨）、メール認証コード、またはメールアドレスとパスワードでログインします
0	auth_email_code	メール認証コードでログインします。CAPTCHA 画像を取得してコードを送信します（すべてチャット内で完結）
0	auth_status	現在のログイン状態を確認します
0	formlm_usage	アカウントの利用状況を一覧で確認します。プラン、アプリ枠の使用状況、AI クレジットを一括作成の前に確認できます
1	formlm_generate	実行計画を生成します（フェーズ 1：アプリを作成し、appId とタスクを返します）
1	formlm_execute	formlm_generate の後に、計画のモジュールを 1 つずつ実行します
2	formlm_doctor	1 つのアプリを読み取り専用で品質監査します（スコアの網羅性、使用されていないエキスパート、スタイル、証明書ページ、言語の一貫性、共有アクセス、到達可能性）
2	formlm_snapshot	すべてのモジュールの状態を集約します。summary: true を指定すると、簡潔な監査プロファイルを返します
2	formlm_skill	スキルモジュールのドメイン知識を記載した SKILL.md を取得します
3	formlm_exec	許可リストに登録された任意の CLI コマンドを直接実行します

利用可能な MCP リソース（6）

Resource URI	Description
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 — アクセスタイプ、冪等性

---

環境変数

Variable	Description
FORMLM_BASE_URL	FormLM サーバーの URL（デフォルト：https://formlm.me）
FORMLM_TOKEN	認証トークン（auth login の代わりに使用できます。シェル履歴に秘密情報を残しません）
FORMLM_JSON=1	機械可読形式で出力します。すべてのコマンドが stdout に解析可能な 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 は常に解析済みです（再度デコードする必要はありません）。また、検証エラーやパラメーターエラーは、エラーテキストを data 内に隠して成功として報告するのではなく、ゼロ以外の code とともに返されるようになりました。

ステータスコード

コード	意味	対処方法
0	成功	—
207	部分的（複数モジュールの読み取りで、1つのモジュールが失敗）	結果に_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は、メッセージにapp-limit:を含む403を返します。formlm.me → Workspace → #/vipでアップグレードしてください
アカウントあたりのAIコマンド数	60セグメント/分（smart plan／smart execute／expert chat。smart generateを1回すべて実行すると約7セグメント）	rate-limit:を含む429が返されます。速度を落とすか、FORMLM_CONCURRENCYを4以下にしてください
生成されたアプリごとのAIクレジット	完了したスマート生成は、すべてのモジュールの実行後に**1回の課金イベント（約20クレジット）**として精算されます。新しいアカウントには約100クレジットが無料で付与されます	差し引きはゼロを下回らず、生成がブロックされることはありません（ウェブアプリと同じ動作です）
エキスパートチャットの利用	アプリごとの1日の計算予算＋アカウントごとの1日のラウンド上限	メッセージに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を引き上げてください。
• 多数のアプリを1つのプロセス内でバッチ処理するには、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 への解決がサーバー側に移動したため、raw exec でも効果があります）
✔	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