fcode-cli

Factorial Code — CLI

fcode CLI はプロセスをローカルで開発・テストし、Factorial Code Cloud と同期します。プラットフォームのモデルについては、fcode-core-concepts を参照してください。

コマンドの流れ

マシンで初めて使う場合：pnpm install -g @factorialco/fcode-cli でインストールし、続いて fcode clone <workspace-slug> を実行して、クラウドのワークスペースを <workspace-slug>/ フォルダーに取得します（このときエージェントスキルもインストールされます。--skipSkillsSetup を指定するとスキップできます）。アプリの「開発」タブにある「ローカルでビルドする方法」ガイドには、その開発用ワークスペースの正確な clone コマンドが表示されます。スラッグはエンコードされたトークンで、アプリの UUID ではないため、そこからコピーしてください。開発チームが所有するすべてのアプリを 1 つのレイアウトに取得するには、代わりに fcode team:clone を使います（以下を参照）。

すでにクローン済みのワークスペースで変更を加えてテストする場合：

1. fcode pull (必要に応じて最初に実行) — クラウド側が変更されている可能性がある場合は、最新バージョンで作業できるよう同期します。
2. ローカルファイル（プロセス、モジュール、変数、依存関係）を編集します。
3. fcode add — 新しいリソースを作成した場合に限り実行します（新しいプロセス、モジュール、依存関係、または変数）。既存コードの編集では不要です。
4. fcode dependencies:install — dependencies/package.json または dependencies/requirements.txt を変更した場合に実行します。
5. fcode run <process-slug> — プロセスをローカルで実行してテストします。
6. fcode push — 準備ができたらクラウドにデプロイします。

プッシュで更新されるのは、現在の（バージョン管理されていない）コードのみです。stable エイリアスを指定している利用者（Webhook URL とフォーム埋め込みでは常にこのエイリアスを使ってください）は、エイリアスが切り替わるまでリリース済みバージョンを引き続き実行します。リリース（ワークスペースのバージョンを公開して stable の参照先を切り替えること）は別途行い、通常は Web UI から実行します（以下を参照）。

注意点

• プロセス（またはその他のリソース）を作成した直後に fcode add の前に fcode run を実行しないでください。「Local process not found」というエラーが発生します。
• **fcode add は新しいリソース専用です。**既存のプロセス／モジュールのコードや変数を編集する場合は、そのまま fcode push を実行してください。
• **push／pull の --force は、反対側の内容を上書きします。**ローカルとクラウドの内容が異なる場合、どちらのコマンドも失敗します。上書きされていない settings.json が消去されないようにする settings:pull も同様です。まず fcode diff を実行して、破棄される内容をユーザーに正確に示してください。また、明示的なユーザー確認がある場合に限り --force を使用してください。
• settings.json の versions／aliases を編集すると、プッシュ時にリリースが行われます。タグを追加するとそのワークスペースのバージョンが公開され、タグを削除するとクラウドからそのバージョンが削除されます（連鎖的に削除されます）。エイリアスの参照先を変更すると、リリースまたはロールバックになります。settings:versions:*／settings:aliases:* と同じルールです。明示的に依頼されない限り、変更しないでください。
• 継承されたリソースは編集しないでください。variables.inherited.env、i18n/<locale>.inherited.yaml、および継承されたプロセス／モジュールは親ワークスペースが所有し、pull 時に再生成され、push されません（以下を参照）。変数を上書きするには、キーを variables.env に追加します（ロケールキーの場合は i18n/<locale>.yaml に追加します）。プロセスとモジュールは、それらを所有するワークスペースで編集してください。

コマンド

fcode add

ローカルの新しいリソースを CLI に登録し、実行またはデプロイできるようにします。新しいプロセス／モジュール／依存関係／変数を作成した後、run／push の前に実行してください。既存のリソースを編集しただけの場合は不要です。

fcode dependencies:install

依存関係をローカルのワークスペースにインストールします。dependencies/package.json または dependencies/requirements.txt を変更した後に実行してください。継承されたパッケージもインストールされるため、ローカル実行時にクラウドと同じ依存関係を解決できます。

fcode run <process-slug> --parameters <filepath | json>

開発／テスト用に、プロセスをローカルで実行します。variables.env / variables.local.env と指定されたパラメーター（指定がない場合はプロセスの parameters.json）を使用します。ログ、結果、エラーが表示されます。

fcode run my-process --parameters '{"key": "value"}'
fcode run my-process --parameters ./params.json
fcode run my-process                                  # default parameters.json
fcode run my-process --locale pt-BR                   # resolve fcode.i18n in that locale

前提条件：リソースを作成したばかりの場合は、先に fcode add を実行してください。

--locale は、クラウドとまったく同じ方法で、ローカルの i18n/ ファイルを使って fcode.i18n を解決します。詳しくは fcode-i18n を参照してください（フラグの入力ミスがあると、すべてのキーがそのまま返される理由も説明しています）。

fcode http

ローカル HTTP サーバー（--port、デフォルトは 3000）を起動します。クラウドの Webhook 環境を再現し、ワークスペースのフォームスキーマも提供するため、デプロイせずに Webhook でトリガーされるプロセスやフォームを実行できます。

--auth-user / --auth-password を設定すると、ローカルサーバー全体が基本認証で保護されます。プロセスごとの Webhook 認証はこれとは別で、クラウドとまったく同じ方法で適用されます。サーバーはプロセスの metadata.json から webhook.authMode を読み取り、settings.json の webhookAuth に対して TEAM を解決し、設定されたヘッダー内に指定された変数の値があることを要求します。Authorization の場合は Bearer <token>、それ以外のヘッダーの場合は値そのものです。値には、すべてのローカル実行で使用される優先順位に従ってワークスペース変数が使われます。variables.inherited.env が最初に適用され、variables.env、variables.local.env（後述）で上書きされます。ヘッダー名の照合では大文字と小文字を区別しませんが、ヘッダーが重複している場合は結合せずに拒否します。ヘッダーがない場合、Bearer 値の形式が不正な場合、変数が未定義の場合、値が一致しない場合、またはワークスペース設定がない TEAM Webhook の場合は、いずれも 403 が返され、理由がコンソールに表示されます。

ローカルでの注意点が 2 つあります。

• シークレット変数は ******** というプレースホルダーでダウンロードされるため、実際の値を variables.local.env に設定するまでは、ローカル認証で受け付けられるのは ******** のみです。
• --auth-user / --auth-password は Authorization ヘッダーを使用するため、同じ場所に認証情報を要求する Webhook とは併用できません。サーバーは起動時にこの点を警告します。

fcode pull

クラウドから最新のプロセス、モジュール、変数、依存関係をダウンロードし、ローカルファイルを上書きして一致させます。他のユーザーがクラウドリソースを変更した可能性がある場合は作業開始前に実行してください。また、ローカルの変更を破棄する場合にも使用できます。--force は、ユーザーが確認した場合にのみ使用できます。

fcode push

ローカルの変更をクラウドにアップロードします。ローカルで変更を加えた後に実行してください（新しいリソースを作成した場合に限り、先に fcode add を実行します）。先に fcode run を実行することを推奨します。--force は、ユーザーが確認した場合にのみ使用できます。

fcode status

ローカルとクラウドのどちらも変更せず、プロセス、モジュール、変数、依存関係、ロケール、settings.json の差分を報告します。リソースごとのコマンドもあります：processes:status、 modules:status、variables:status、i18n:status、settings:status。

クラウドと一致している継承リソースは表示されません。プルもプッシュも不要なためです。省略されたリソースの数は行に表示されます。継承リソースに差分が生じると、最新ではない、新規、削除済み、競合、変更済み、機密性変更のいずれの場合も再び表示されるため、親リソースの移動が気付かれないまま処理されることはありません。--showInherited を指定すると、すべて表示されます。

fcode status --showInherited        # or any per-resource variant above

継承された機密変数も、変更なしとして扱われ、非表示になります。値は比較されないため、最新の状態として報告されることはありません。

fcode diff [<slug>]

status が何かが異なると示すだけなのに対し、何が異なるのかを表示します。ワークスペースが保存されているすべてのファイルを対象とした、Git 形式の統合差分です。クラウド側を旧バージョン、ローカルファイルを新バージョンとして扱います。リソース別のバリエーションでは、オプションでスラッグを指定できます：processes:diff、modules:diff、variables:diff、i18n:diff、dependencies:diff、settings:diff。

fcode diff                          # the whole workspace
fcode processes:diff my-process     # one process

pull／push で 🔥 (conflict) を解決する前に実行し、どちらを選ぶと各側で何が失われるのかをユーザーが確認できるようにしてください。注意事項：

• ローカルとクラウドが異なる場合は 1、同期済みの場合は 0 で終了します。チェックとして使用できます。ここでのゼロ以外の終了コードは答えを示すものであり、エラーとして報告する必要はありません。
• 機密性の高い変数の値は表示されません。両方の側で <sensitive value hidden> と表示されるため、変更されたシークレットは status には表示されますが、ここには表示されません。
• 継承されたリソースには status と同じルールが適用されます。クラウドが一致を確認したリソースは件数のみが表示され、親が移動したリソースは所有するワークスペースとともに差分が表示されます。これらは読み取り専用のままなので、修正するには fcode push ではなく fcode pull を使用してください。継承された変数は、保存先の生成ファイルである variables.inherited.env として差分が表示されます。

fcode remote:add <workspace-slug>

すでにクローン済みのワークスペースフォルダーを別のクラウドワークスペースに紐付け、以降の fcode pull／push の同期先を切り替えます。これはワークスペース間でコードを昇格させる方法です（例：dev → prod）。場当たり的に使用しないでください。ゲート付きの昇格手順については fcode-release を参照してください。

fcode team:clone／team:pull／team:status

開発チームが所有するすべての App をまとめて扱います。ここでいうチームとはダッシュボード上の人間のチームであり、ワークスペースの意味でのチームではありません（fcode-ama を参照）。引数なしで team:clone を実行すると、所属する開発チームの一覧が表示され、ID をコピーできます。引数を 1 つだけ指定すると、そのまま処理が進みます。

fcode team:clone                 # lists your teams, or clones the only one
fcode team:clone <teamId>

App ごとに 1 つのフォルダーを作成します。このフォルダーには App のメタデータファイルと、その App のワークスペースのチェックアウトが含まれます。

acme-payroll/
┣ 📂 .fcode/team.json      # the team and the Apps cloned into it
┣ 📂 .claude/skills/       # installed once, symlinked into every App below
┗ 📂 payroll-sync/
  ┣ 📜 settings.json       # the App — name, description, id (mirror)
  ┣ 📜 README.md           # the App's README — yours, pushed with `fcode app:push`
  ┣ 📜 MARKETPLACE.md      # the marketplace listing — yours, pushed with `fcode app:push`
  ┣ 📜 CHANGELOG.md        # generated from the App's releases (mirror)
  ┣ 📂 marketplace/logo.*  # the App logo set in the dashboard (mirror)
  ┗ 📂 app/                # a normal workspace — settings.json, processes/, …

チェックアウトの名前は app であり、元になった dev-<token> スラッグではありません。スラッグはメタデータに記載され、ディレクトリはチェックアウトにすぎないため、fcode remote:add で prod ワークスペースに切り替えられます。各階層の settings.json は、その階層に含まれる対象について記述します。階層がディレクトリで分かれているため、互いに衝突することはありません。

App のワークスペース内では通常のコマンドをいつもどおり使えます。チームコマンドで追加されるのは、複数の App にまたがるコマンドだけです。

• team:pull はチーム情報を読み直します。前回の実行以降に追加された App をクローンし、すべてのワークスペースをプルして、各 App のメタデータファイルを更新します。チームから外れた App は報告されますが、削除されません。削除したい場合は、自分でフォルダーを削除してください。
• team:status は各 App の README.md と MARKETPLACE.md の状態（最新、ローカルで変更済み、古い、競合）を報告し、その後、App ワークスペース内で fcode status を独自の見出しの下で実行します。
• team:push はありません。 コードはワークスペース内から App ごとにプッシュします。App の README と掲載情報は fcode app:push（以下を参照）でアップロードします。
• App フォルダーのファイルは 2 種類あります。ミラーである settings.json、CHANGELOG.md、marketplace/logo.* は、プルのたびに書き換えられます。これらを編集しても、上流には何も反映されません（App の名前はダッシュボードで変更してください。リリースノートはリリースをリクエストする際に入力するコメントです）。ユーザーが管理するファイルである README.md と MARKETPLACE.md は、編集後も保持されます。プルで上書きされるのは、前回の同期以降に変更していないファイルだけです。保持されたファイルは報告されます。
• App で失敗が発生しても、実行全体は中断されません。失敗した App は概要に表示され、team:pull を再実行すると、まだ不足しているものだけが再試行されます。ダッシュボードから取得できなかったメタデータファイルはそのまま残り、警告として報告されますが、App のクローンが失敗することはありません。

fcode app:push

App フォルダーの README.md と MARKETPLACE.md をダッシュボードにアップロードします。App フォルダー、またはその app/ チェックアウト内の任意の場所から実行できます。settings.json と app/ の組み合わせによってフォルダーを識別します。移動するのはドキュメントのみで、コードは移動しません。

cd payroll-sync
fcode app:push            # uploads the files that changed since the last sync
fcode app:push --force    # local wins over a cloud edit

• README.md は App の README で、ダッシュボードの App ページにある README タブにも表示され、そこで編集できます。空のファイルをアップロードすると README が消去されます。クラウド上の README が一度も作成されていない場合は、スタブ（# <App name> と説明文）としてダウンロードされるため、編集できるファイルが存在します。
• MARKETPLACE.md は Publication タブの掲載情報です。YAML フロントマターには tagline、category_id（DatoCMS のカテゴリー ID）、support_link、help_link（http(s):// または mailto:）を指定し、その後に説明文全体（Markdown、1～5000 文字）を本文として記述します。ダッシュボードが管理するフィールドである publication_state と datocms_id はコメントとして表示され、アップロードされません。DatoCMS のレコードがリンクされている場合、マーケットプレイスではこれらのフィールドよりもリンク先のレコードが優先されます（fcode-ama を参照）。
• 競合：前回のプル以降にローカルとダッシュボードの両方でファイルが変更されている場合、アップロードは拒否されます。--force を指定するとローカルファイルが優先されます。ファイルを削除して fcode team:pull を実行すると、ダッシュボード側が優先されます。クラウドより古いだけのファイルはスキップされ、プルするよう案内されます。
• ダッシュボードがファイルを拒否した場合、該当するフィールドと理由（例：タグラインが 140 文字を超えている）が報告されます。他方のファイルは引き続きアップロードされ、コマンドはゼロ以外の終了コードで終了します。
• アップロード後、ローカルファイルはプルした場合と同じ正規形式に書き換えられるため、team:status では最新と判定されます。

fcode settings:pull / settings:push / settings:status

ワークスペースレベルの settings.json の設定を個別に同期します。settings:pull はクラウドの設定をファイルに書き込み、settings:push はファイルの内容を適用し、settings:status はローカル、クラウド、またはその両方で変更されているかを報告します。通常の fcode pull / fcode push にもこれらの設定が含まれます。参照先のエラーハンドラープロセスのスラッグを既存のプロセスに対して解決できるよう、最後に実行されます。

versions / aliases フィールドも、ファイルのほかの部分と同様に同期されます。settings:push はクラウドとの差分を確認して適用します。ローカルに記載されていてクラウドにはまだないバージョンを、comment を引き継いで公開します。ファイルから削除されたバージョンを削除する前には、バージョンごとに確認を求めます（削除は連鎖的に実行されます。--force を指定すると確認を省略します）。また、一致するようにエイリアスを作成、参照先変更、削除します。settings:status でもこれらを比較し、settings:pull は未プッシュのローカル変更がある settings.json の上書きを拒否します。

fcode settings:versions:* / fcode settings:aliases:*

ワークスペースのバージョン管理では、ワークスペース全体のバージョンを公開します。チームが所有するすべてのプロセスとモジュールに同じタグのバージョンが付与され、公開されたスナップショット内では、モジュールのベアインポートがそのバージョンに固定されます（モデルについては fcode-core-concepts を参照してください）。通常、リリースはウェブ UI（チーム設定 → Versions タブ）から行います。これらのコマンドは命令型の方法で、settings.json の versions / aliases を編集してプッシュするのは宣言型の方法です。明示的に依頼されない限り、バージョンを作成したり stable を移動したりしないでください。

fcode settings:versions:create v1.0.0 --comment "First stable release"
fcode settings:versions:list
fcode settings:versions:delete v1.0.0     # cascades; asks confirmation unless --force

fcode settings:aliases:set stable v1.0.0  # create or re-point; rollback = older tag
fcode settings:aliases:list
fcode settings:aliases:delete stable

• settings:versions:create は、すでに完全一致するタグが付いているエンティティをスキップし、エンティティごとの概要（作成済み／スキップ／失敗 — バージョンのマニフェスト）を報告した後、プルを実行して versions/<tag>/ フォルダーと settings.json をローカルで更新します。一部失敗した後に同じタグで再実行すると、まだ存在しないものだけが公開されます。
• settings:versions:delete は連鎖的に削除します。そのタグが付いた、所有するすべてのプロセス／モジュールのバージョンが、参照しているエイリアス、実行、スケジュールとともに削除されます。
• settings:aliases:set はアップサートします。公開済みの対象タグがある、所有する各エンティティに対してエイリアスを作成するか、既存のエイリアスの参照先を変更します（対象タグがないエンティティはスキップされ、報告されます）。stable の参照先を以前のタグに変更することがロールバックです。stable に固定されているすべての利用者が、1回の操作で切り替わります。

fcode i18n:*

i18n:pull / i18n:push / i18n:status / i18n:add <locale> / i18n:remove <locale> / i18n:reset は、ワークスペースの翻訳ファイル（i18n/<locale>.yaml と、pull が書き込む読み取り専用で Git の追跡対象外の i18n/<locale>.inherited.yaml）を同期します。集約コマンドの fcode pull / push / status には、すでにロケールが含まれています。ファイル形式、継承モデル、国際化ワークフローについては fcode-i18n を参照してください。

プロセスのメタデータ — metadata.json

各プロセスフォルダーには processes/<slug>/metadata.json があり、プロセスの名前、説明、タグ、トリガー、設定の信頼できる情報源となります。push / pull で双方向に同期されます。ファイルを編集して fcode push を実行すると、ダッシュボードを使わずにクラウド上のこれらの設定を変更できます。変更は fcode status で 🔺 modified と表示されます。

フィールド	型	意味
name	string	表示名（デフォルトはスラッグ）
description	string, optional	プロセスの説明
tags	string[]	タグ（デフォルトは []）
webhook	object, optional	Webhook トリガー：enabled（boolean）はプロセスの Webhook エンドポイントを有効にします。authMode（NONE | TEAM | CUSTOM）は呼び出し元の認証方法を指定します。公開、settings.json のワークスペース webhookAuth を継承、または独自の認証方法から選択できます。auth（{ headerName?, variableKey }、CUSTOM の場合のみ）は、ヘッダー名と、想定されるトークンを格納するチーム変数を指定します
factorial	object, optional	プロセスを Factorial Action として Factorial に公開する方法（fcode-factorial-actions を参照）：enabled（boolean）はマスタースイッチ、awaitResult（boolean、デフォルトは true）は Factorial が結果を待機するかどうか、requiredPolicies（string[][]）は Factorial ポリシーキーの AND グループを OR で組み合わせたものです。また、各エントリーポイントにそれぞれ enabled を持つサブブロックを指定します。uiTrigger（locationId は有効化時に必須、≤ 200 文字。label は fcode.i18n("key") トークンを使用できる唯一のフィールドです。icon）、form（appTool は Factorial のアプリ独自ページでフォームを提供します。public は非推奨です）、agentTool（Factorial One のツール契約：description、effect は READ | WRITE | DESTRUCTIVE — 未設定の場合は破壊的として扱われます —、whenToUse、whenNotToUse[]、preconditions[]、doesNotDo[]、degradation、simulatesFor）、および backend
form	object, optional	レガシー。factorial.form とミラーリングされます：enabled（boolean）は Forms フラグです（fcode-forms を参照）。appRole（INSTALL、SETTINGS、USER_FACING_FORM、UNINSTALL）：USER_FACING_FORM は現在 factorial.form.appTool に対応していますが、3 つのライフサイクル値にはこのブロック内に対応するものがないため、ここに残ります（予約済みのライフサイクルスラッグは代替手段であり、置き換えるものではありません。fcode-factorial-actions を参照）。authMode（FACTORIAL、NONE）は呼び出し元に Factorial アカウントが必要かどうかを決定し、factorial.form.public がその切り替えを行います
uiTrigger	object, optional	レガシー。factorial.uiTrigger とミラーリングされます（fcode-ui-triggers を参照）：enabled、locationId、label、icon、および awaitResult（現在は factorial.awaitResult）
lifecycleRole	—	ファイルのフィールドではありません：INSTALL | SETTINGS | UNINSTALL | SYNC。プラットフォームがプロセスの form.appRole から導出します。指定がない場合は、予約済みスラッグ install、settings、uninstall、sync から導出します。CLI と API で報告されますが、metadata.json には書き込まれません（fcode-factorial-actions を参照）

{
  "name": "Order sync",
  "description": "Syncs Shopify orders into Factorial",
  "tags": ["integration", "shopify"],
  "webhook": {
    "enabled": true,
    "authMode": "CUSTOM",
    "auth": { "variableKey": "SHOPIFY_WEBHOOK_TOKEN" }
  },
  "form": { "enabled": false }
}

ワークスペース設定を継承する Webhook は "webhook": { "enabled": true, "authMode": "TEAM" } を持ち、公開 Webhook は "webhook": { "enabled": true } のみを持ちます。

Factorial に公開するプロセスには factorial ブロックが含まれます。レガシーの form キーと uiTrigger キーが存在する場合は、引き続きこれらとミラーリングされます：

{
  "name": "Approve pending time off",
  "tags": ["timeoff"],
  "factorial": {
    "enabled": true,
    "awaitResult": false,
    "requiredPolicies": [["company.manage_timeoff"], ["company.admin"]],
    "uiTrigger": { "enabled": true, "locationId": "calendar.header.admin", "label": "fcode.i18n(\"acme.approve.button\")", "icon": "Bell" },
    "form": { "enabled": true },
    "agentTool": {
      "enabled": true,
      "description": "Approves every time-off request still pending for a team.",
      "effect": "WRITE",
      "whenToUse": "The user asks to approve the pending time-off requests of a team.",
      "whenNotToUse": ["The user wants to approve a single, named request."],
      "preconditions": ["The team has at least one pending request."],
      "doesNotDo": ["It does not notify the employees whose requests were approved."]
    },
    "backend": { "enabled": true }
  }
}

マーケットプレイスアプリのインストールフォームは、フォームを有効にした 予約済みスラッグ install のプロセスそのものです（プラットフォームはそこから lifecycleRole を導出します）：

{
  "name": "Connect your account",
  "tags": ["setup"],
  "factorial": { "enabled": true, "form": { "enabled": true } }
}

注意事項：

• webhook.auth.variableKeyには変数の名前のみを保存し、トークンは保存しません — そのため、このファイルは安全にコミットできます。変数はまだ存在していなくてもかまいません。存在するまでは、Webhookへのすべての呼び出しが403で拒否されます。通常の変数とシークレット変数の両方を使用できます。
• authMode: TEAMはsettings.jsonのwebhookAuthを継承します。 この設定がない場合、Webhookはすべての呼び出しを拒否し、パブリックとして扱われることはありません。MCP経由では、この点が重要になります。エージェントはauthMode: TEAMを設定できますが、チーム設定用のツールはないため、設定がすでに存在している必要があります（settings.jsonに設定してfcode settings:pushを実行してください）。
• **webhook.auth.headerNameのデフォルトはAuthorization**で、その値はBearer <token>である必要があります。それ以外のヘッダーには、変数の値をそのまま指定します。有効な名前はRFC 7230のトークン文字で構成され、最大64文字です。また、Cookie、Host、およびFcode-で始まる名前は使用できません。デフォルト値を推奨します。独自のヘッダーでは、Authorizationに適用される秘匿化がプロキシやログパイプラインで行われません。送信側がAuthorizationを設定できない場合に限り、独自のヘッダーを使用してください。その例が、トークンをx-factorial-wh-challengeに設定するFactorial独自のWebhook送信機能です。
• form.appRoleとwebhook.authModeは未設定またはNONEの場合に省略されます。webhook.auth.headerNameもAuthorizationの場合は省略されるため、フォームには"form": { "enabled": true }のみが含まれます。保護されたWebhookの保護を解除するには、"authMode": "NONE"を明示的に記述してください。このフィールドを省略すると、保存済みのモードが維持されます。また、authMode: CUSTOMを指定せずにauthを送信すると拒否されます。
• 新しいプロセスでは、インストール／設定／アンインストールには予約済みのライフサイクルスラッグを、Appが独自のページで提供するフォームにはfactorial.form.appToolを使用し、form.appRoleは使用しないでください。すでに公開済みのAppでは、appRoleをライフサイクルフォームの名前として引き続き使用できます。移行期限はありません。引き続きappRole: USER_FACING_FORMを含むファイルをプッシュすると、そのロールが維持されます。appToolがない場合、CLIはロールから値を導出し、そのロールをレガシーキーから送信しなくなります。
• factorialブロックではデフォルト値も省略されます。awaitResultはtrueの場合、requiredPoliciesは空でない場合、form.publicとform.appToolはfalseの場合、agentToolのテキストは未設定の場合、リストは空でない場合に省略されます。また、enabledがfalseのサブブロックも省略されます。Factorialに公開されていないプロセスにはfactorialキー自体がありません。コントラクトがまだないFactorial Oneツールは、"factorial": { "enabled": true, "agentTool": { "enabled": true } }のみです。locationIdを指定せずにfactorial.uiTriggerを有効にしてプッシュすると拒否されます。
• プッシュするたびに、フォームがパブリックかどうかが決まります。 factorialブロックを含むファイルは常にform.publicを送信し、プラットフォームはその値から認証モードを書き込みます。そのため、コンソールでパブリックに公開したフォームでも、"public": trueの指定がないファイルから次にプッシュすると、再びFactorialアカウントが必要になります。先にfcode pullを実行するか、ファイルにフラグを設定して維持してください。
• ファイルにfactorialとレガシーのform／uiTriggerキーの両方が含まれる場合、fcode pushはfactorialを送信します。プラットフォームはそれをレガシーブロックに反映します（ルールはfcode-factorial-actionsを参照）。ブロックの初期ドラフトに含まれていたfactorial.title／factorial.descriptionはプッシュ時に無視され、プル時に削除されます。
• fcode pullは引き続き、すべてのプロセスに"uiTrigger": { "enabled": false }を書き込みます（レガシーブロック）。そのlocationId、label、iconは設定されている場合のみ、awaitResultはtrueの場合のみ記載されます。
• metadata.jsonがない場合、fcode addは{ "name": "<slug>", "tags": [] }をひな型として作成します。無効なJSONの場合は、警告を表示してこれらのデフォルト値にフォールバックします。

Webhook の呼び出し — URL でバージョンを固定する

Webhook エンドポイントは https://code.factorialhr.com/platform/api/<team-slug>/webhooks/<process-slug>です。 サブスクリプションシステムではリクエストヘッダーを設定できないことが多いため、version_tag クエリパラメーターで stable エイリアスを指定し、常にバージョンを固定してください：

curl -X POST "https://code.factorialhr.com/platform/api/<team-slug>/webhooks/<process-slug>?version_tag=stable"

• version_tag にはバージョンタグ（v1.0.0）またはエイリアスを指定します。stable を使用してください。これは常に存在するため、エイリアスを移動するだけでリリースやロールバックができ、外部システムを変更する必要はありません。これは Fcode-Version-Tag ヘッダーと同等で、ヘッダーより優先されます。version_tag、async、locale は予約名であり、パラメーターがプロセスに渡される前に取り除かれます（locale は実行時の言語を選択します。fcode-i18n を参照してください）。
• バージョンが不明または不正な形式でも、呼び出しは失敗しません。 プロセスは現在のバージョンで実行され、プラットフォームはサーバー側で警告をログに記録するだけです。つまり、入力ミスがあっても現在のバージョンがそのまま実行されます。実行が予期しない動作をした場合は、実行のバージョンを確認してください。

ワークスペース設定 — settings.json

ワークスペースのルートに置く、ワークスペースレベルの設定を保持する単一ファイルです。 fcode settings:pull / settings:push / settings:status で同期され、通常の fcode push / pull にも含まれます（参照先のエラーハンドラープロセスが先に 存在するよう、最後にプッシュされます）。

フィールド	型	意味
parentTeams	array	このワークスペースがプロセス、モジュール および変数 を継承するチーム（直接の親のみ、最大 5 件）。各エントリーはプレーンなスラッグ（親の状態を常に最新の状態で参照）または { slug, version } で、親をそのワークスペースバージョンのいずれか（タグまたはエイリアス）に固定します
zoneId	string, optional	チームのタイムゾーン（スケジュールなどに使用）
errorHandlerConfig	object, optional	{ "processSlug": "<slug>", "tag": null } — 実行エラー時に呼び出されるプロセスです。tag を指定すると、バージョンタグまたはエイリアスに固定されます（null = 現在のバージョン）
webhookAuth	object, optional	{ headerName?, variableKey } — authMode: TEAM のすべての Webhook が継承する設定です
primaryLocale	string, optional	ワークスペースの主要言語です。呼び出し元が言語を指定しない場合に使用されるロケールであり、翻訳されていないキーのキー単位のフォールバックです（fcode-i18n を参照）
versions	array, optional	ワークスペースのバージョン：{ tag, comment?, createdAt? } — 新しい tag を宣言してプッシュすると公開されます。createdAt は省略してください。クラウド側で設定されます
aliases	array, optional	ワークスペースのエイリアス：{ name, tag }

{
  "parentTeams": ["shared-utils", { "slug": "base-app", "version": "stable" }],
  "zoneId": "Europe/Madrid",
  "errorHandlerConfig": { "processSlug": "error-handler", "tag": null },
  "webhookAuth": {
    "headerName": "x-factorial-wh-challenge",
    "variableKey": "FACTORIAL_CHALLENGE_TOKEN"
  },
  "versions": [
    { "tag": "v1.0.0", "comment": "First stable release", "createdAt": "2026-08-01T10:00:00" }
  ],
  "aliases": [{ "name": "stable", "tag": "v1.0.0" }]
}

エラーハンドラーは ID ではなくスラッグ で参照されるため、settings.json は ワークスペース間で移植可能です。CLI はプッシュ時にクラウド ID に解決します。

parentTeams のエントリーは、親の状態を常に最新の状態で参照する場合はプレーンな スラッグとして、固定後は { slug, version } として記述されます。読み込み時には どちらの形式も受け付けるため、スラッグだけを手書きしたリストも有効です。 version は その親の ワークスペースバージョンのタグまたはエイリアスであり、 親に存在しない場合はプッシュが拒否されます。固定によって何が変わるかは fcode-core-concepts に記載されています。明示的に依頼された場合を除き、 固定を追加または変更しないでください。

versions と aliases は読み取り専用のミラーではなく、同期対象の状態 です。 コンテンツハッシュに含まれるため（編集すると fcode status で変更済みと表示されます）、 settings:push で上記の差分の扱いに従って適用されます。比較対象となるのはタグの 集合と name → tag の対応関係のみです。公開済みバージョンの comment は変更できず、 createdAt はサーバー側で割り当てられます。

webhookAuth はワークスペース全体で共有される設定なので、複数の Webhook で使用する トークンは、1 か所で名前を付けてローテーションできます。次の 2 点に注意してください。

• ワークスペースごとの設定であり、parentTeams を通じて継承されません。 認証はコードを所有するワークスペースではなく、Webhook URL で指定された ワークスペースを基準に解決されます。そのため、ベースアプリから Webhook プロセスを 継承するアプリにも、独自の webhookAuth エントリーが必要です。
• オブジェクトを削除してプッシュすると、クラウドの設定が消去されます。 その結果、これを継承するすべての Webhook がすべての呼び出しを拒否するようになります。

ディスク上の継承リソース

fcode pull は、parentTeams から継承したすべてのリソースを、ワークスペース固有のリソースと並べて書き込みます。対象は、variables.inherited.env、i18n/<locale>.inherited.yaml、dependencies/package.inherited.json／ requirements.inherited.txt、および processes/ と modules/ 内の継承されたプロセス／モジュールフォルダーです。CLI はこれらを親の所有物として扱います。

• 読み取り専用 — プロセス／モジュールのファイルはモード 444 で書き込まれます。編集に chmod が必要なら、編集を中止して、所有元のワークスペースで変更してください。
• Gitignore 対象 — .gitignore 内の CLI 管理ブロックによって除外され、pull のたびに再生成されます。このブロックを手動で編集しないでください。
• fcode push でアップロードされることはありません。 ローカルで変更されたファイルがあると、所有するチーム名を示す警告がログに出力されます。fcode processes:pull／ modules:pull（または一括で fcode pull）を使って復元してください。
• *:status コマンドでは、クラウドと異なる継承リソースのみが一覧表示されます（残りを表示するには --showInherited を指定）。各項目には、所有するワークスペースを示す inherited 列（🔗 <slug>）が表示されます。
• ピン留めした親から取得するのは、そのバージョンの内容であり、親の現在のコードではありません。 また、ピン留めしたバージョンが公開したリソースのみが対象です。親が後から追加したプロセスは一切 pull されません。settings.json でピンを変更して再度 pull すると、それらのファイルが更新されます。

継承モデル（解決順序、オーバーライド、ピン留め）については fcode-core-concepts を参照してください。

3 つの変数ファイル

チーム変数は、ワークスペースのルートにある 3 つの .env ファイルに保存されます。

ファイル	内容	同期
variables.env	このワークスペースが所有する変数	コミット対象。push および pull されます
variables.inherited.env	親ワークスペース（parentTeams）から継承した変数	pull のみ。gitignore 対象（CLI がエントリーを追加します）
variables.local.env	ローカルのみのオーバーライド	push も pull もされません

ローカル実行時の解決順序（優先度の高い順）はクラウドの動作と同じです。 variables.local.env → variables.env → variables.inherited.env。

優先順位は値ではなく、キーを宣言しているファイルによって決まります。そのため、variables.env でキーの値を空にすると、親の値にフォールバックせず、継承変数が空文字列でオーバーライドされます。

継承変数のオーバーライド

キーを variables.env に追加することが、オーバーライドになります。 その時点から、CLI はその変数をこのワークスペース固有の変数として扱います。fcode status では新規として表示され、fcode push でこのワークスペースに作成され、fcode variables:add の候補にも表示されます。

• 「利用可能にする」ために、親の変数を子ワークスペースにコピーしないでください。変数はすでに解決されます。このワークスペースで別の値が本当に必要な場合にのみキーを追加してください。（継承機能の導入前にプロビジョニングされたワークスペースには、そのようなコピーが残っており、現在は親の変数をシャドウしている場合があります。変更されていない ******** プレースホルダーも、通常なら解決されるシークレットをシャドウします。これらは削除せず、ユーザーに知らせてください。）
• オーバーライドを削除（variables.env からキーを削除して push）すると、親の値が再び使われます。

モデルと Web UI の動作については fcode-core-concepts を、ランタイムにおける fcode.variables の動作については fcode-javascript／fcode-python を参照してください。

ファイル名は設定項目（variablesFileName、 inheritedVariablesFileName、localVariablesFileName）です。ワークスペースで別途指定されていない限り、上記のデフォルトを前提としてください。

変数の機密性 — variables.meta.json

各変数とその機密性フラグを対応付ける、ワークスペースルートのファイルです。

{
  "ACME_API_KEY": { "isSensitive": true },
  "ACME_BASE_URL": { "isSensitive": false }
}

• fcode variables:add --sensitive で機密変数を作成し（その後、値を設定してプッシュします）、フラグをここに保存します。
• 実行時に fcode.variables.set で作成される変数は、デフォルトで機密情報です。通常の設定には、sensitive: false（JS）／sensitive=False（Python）を渡してください。fcode-javascript／fcode-python を参照してください。
• 機密情報の値がクラウドの外に出ることはありません。pull を実行すると、variables.env にプレースホルダー ******** が書き込まれます。継承されたシークレットの場合は、variables.inherited.env にも書き込まれます。どちらのファイルでもプレースホルダーを置き換えないでください。ローカル実行では、実際の値を variables.local.env に設定してください。リモートでは、継承されたシークレットの実際の値を実行で利用できます（fcode-core-concepts を参照）。マスクされるのはローカルのコピーのみです。
• プッシュ後の isSensitive は変更できません。variables.meta.json で編集すると、プッシュ時に拒否されます（fcode status で 🚫 が表示されます）。リモートの設定に戻してください。

ローカル実行用のシークレット値の取得

ローカル実行（fcode run、検出スクリプト）に、まだ variables.local.env にない実際のシークレット値が必要な場合は、ユーザーに値の提供を依頼してください。ユーザーがエージェントに値を共有したくない場合は、KEY=value の行を自分で variables.local.env に追加してもらってください。ローカル実行では、会話に値を表示することなく、その値を利用できます。

• variables.local.env の値はプッシュされません。 ユーザーには、これらのシークレット変数をリモートのデモ環境でも手動で作成するよう伝えてください。fcode push では値は転送されません。
• FACTORIAL_TOKEN：ローカルでのみ必要です。リモート環境では自動的に設定されるため、リモート環境には作成しないでください。取得するには、ユーザーが Factorial Code アプリの詳細ページで OAuth フローを完了し、OAuth Dev アプリの詳細ページでコピーのドロップダウンオプションを使って生成されたトークンをコピーし、variables.local.env に追加します（または、ユーザーの希望に応じて共有します）。代わりに、インストール済みの特定の企業のコンテキストで実行するには、Test マーケットプレイスアプリのページにある「…」メニューから Copy FACTORIAL_TOKEN を選び、その deploy- ワークスペースのトークンをコピーします。保存先と取り扱い方法は同じです。
• 取得したシークレット値を、出力やログに決して表示しないでください。

例

開発サイクル（新しいプロセス）：

fcode add
fcode dependencies:install            # if dependencies changed
fcode run shopify-order-sync --parameters '{"dateFrom":"2024-01-01","dateTo":"2024-01-31"}'
fcode push                            # no need to re-run `add` if nothing new was created

既存のテスト済みプロセスをデプロイする：

fcode push                            # `add` not needed — process already registered