このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、英語版 を参照してください。
古い difyctl が catalog_stale（The request was built from a catalog that is not this server's current catalog）で失敗するようになった場合、Dify サーバーはすでに 1.18.0 以降に移行しています。
新しいビルドへの切り替え#
新しいビルドのインストール
サーバーに合った difyctl を インストール します。
CI イメージ内など、ほかの場所にある古いビルドのコピーもすべて削除します。新しいビルドでサインインした後に古いビルドの auth logout を実行すると、新しいビルドの保存済みトークンが削除されることがあります。その場合は、もう一度サインインが必要です。
1.17.x 以前のサーバー用に、古いビルドも引き続き必要になることがあります。たとえば、ステージング環境を先に移行し、本番環境はまだ移行していない場合です。そのときは、DIFYCTL_PREFIX で古いビルドを専用のフォルダにインストールし、専用の設定フォルダを指定して実行します。この設定フォルダは最初は空なので、そこで古いビルドでもう一度サインインします：
再サインイン
difyctl describe account で、サインインできたことを確認します。
サインインのオプションと、新しいビルドがトークンを保存する場所については、サインインの管理 を参照してください。CI ジョブでサインインする方法は、CI と自動化での difyctl の使用 を参照してください。
古いセッションの終了
新しいビルドでサインインしても、サーバー上にある古いビルドのセッションは終了しません。このセッションは、既定では最大 14 日間有効です。共有マシンを使っている場合や設定フォルダをコピーした場合など、古いトークンがほかの人の手に渡っている可能性があるときは、すぐに終了させてください。そうでなければ、期限切れになるまでそのままにしてもかまいません。
終了するには、セッションを一覧表示し、difyctl on <your-machine-name> というラベルのセッションを削除します。新しいセッションのラベルは、マシン名だけです。削除時に確認は求められないため、実行前に ID をよく確認してください。
difyctl スキルの再インストール
Claude Code や Codex などのコーディングエージェントが difyctl スキル経由で difyctl を使っている場合は、スキルを再インストールしてください。問題がなさそうに見えても、再インストールは必要です。
古いビルドの skills install --yes は、検出したすべてのコーディングエージェントに difyctl スキルをインストールしていました。次のフォルダのうち、どれが存在するかを確認します：
install skills が difyctl スキルを置き換えるのは、引数に指定したスキルフォルダだけです。引き続き使うコーディングエージェントごとに実行し、残りのスキルフォルダからは difyctl フォルダを削除します：
古い skills install <dir> は、SKILL.md を <dir> の直下に書き込んでいました。コーディングエージェントのスキルフォルダを指定していた場合は、そこに残っている ~/.claude/skills/SKILL.md などのファイルを削除します。
コーディングエージェントが difyctl を使うために必要なその他の準備については、コーディングエージェントのセットアップ を参照してください。
古いコマンドの置き換え#
ほとんどのコマンドは、ID などの値を位置引数ではなく、--app-id のような名前付きフラグで受け取るようになりました。
各コマンドで使えるフラグをすべて確認するには、difyctl help <command> を実行します。
残っているグローバルフラグは --verbose、--json、--help の 3 つだけです。-v、-y、-w などの短縮フラグは廃止されました。--verbose は、エラーにサーバーの生のレスポンスを追加するだけになりました。確認を求めるコマンドはないため、--yes は削除してください。
サインインとセッション#
| 古いビルド | 新しいビルド | 備考 |
|---|---|---|
auth login --host <url> | login --server <url> | --server は必須。--no-browser と --insecure は引き続き使える。 |
auth whoami | describe account | |
auth logout | logout | |
auth devices list | get account session | |
auth devices revoke <id> | delete account session --session-id <id> | --all はない。複数のセッションを終了するには、セッションごとに 1 回ずつ実行する。 |
auth list、use host、use account | なし | サインインは設定フォルダごとに 1 つ。複数のサーバーを使うには、DIFY_CONFIG_DIR でサーバーごとに別の設定フォルダを指定する。アカウントを切り替えるには、サインインし直す。 |
アプリ#
| 古いビルド | 新しいビルド | 備考 |
|---|---|---|
get app | get console_app | --mode、--name、--page、--limit は引き続き使える。 |
describe app <id>、get app <id> | describe console_app --app-id <id> | |
run app <id> "<message>"（チャットボット、レガシー Agent アプリ） | run console_app chat --app-id <id> --query "<message>" | |
run app（Chatflow アプリ） | run console_app advanced_chat --app-id <id> --query "<message>" | |
run app（テキストジェネレーター） | run console_app completion --app-id <id> | |
run app（Workflow アプリ） | run console_app workflow --app-id <id> --inputs '{…}' | |
--inputs-file <file> | --inputs @<file> | |
--file <key>=@<path> | --files '{"<key>":"<path>"}' | Web 上のファイルは --inputs で渡す。 |
--conversation <id> | --conversation-id <id> | |
--stream | --stream | 生の JSON イベントを出力するようになった。--only <event> で絞り込める。 |
--think、--retry-on-limit | なし |
アプリの種類がわからない場合は、describe console_app で確認できます。
チャットボットの実行と、ファイルから入力を渡す Workflow アプリの実行は、次のように変わります：
人間の入力#
人間の入力を待って停止した実行は、"paused" ではなく "status": "suspended" を返すようになりました。paused を確認しているスクリプトは更新してください。この結果の hints には、アクションごとの submit run form コマンドが含まれており、フォームトークンも入力済みです。
フォームを自分で送信する場合、resume app は submit run form に変わります：
resume app と違い、submit run form は実行を追跡しません。実行の続きを取得するには、返されたヒントの get run event を実行します。
DSL のエクスポートとインポート#
| 古いビルド | 新しいビルド | 備考 |
|---|---|---|
export studio-app <id> | export console_app dsl --app-id <id> | YAML をそのままではなく、JSON に包んで出力する。 |
import studio-app --from-file <file> | import console_app dsl --mode yaml-content --yaml-content "$(cat <file>)" | |
import studio-app --from-url <url> | import console_app dsl --mode yaml-url --yaml-url <url> |
エクスポートをファイルに保存するには、.data を取り出します：
古いビルドは保留中のインポートを自動で確定していましたが、新しいビルドは確定しません。ファイルの DSL バージョンがサーバーより新しい場合や、メジャーバージョンが古い場合、インポートは保留中になります。ファイルを信頼できる場合は、confirm console_app dsl_import --import-id <import-id> でインポートを完了します。
古いビルドは、インポート後に不足している統合も一覧表示していました。現在は、check console_app dependency を実行して確認します。
ワークスペースとメンバー#
| 古いビルド | 新しいビルド | 備考 |
|---|---|---|
get workspace Cloud | get workspace | 現在のワークスペースは示されなくなった。difyctl が使用中のワークスペースは describe workspace で確認する。 |
use workspace [<id>] Cloud | use workspace <id> | ID の指定が必須になった。切り替えても、ブラウザのワークスペースは変わらなくなった。サインインし直すか DIFY_WORKSPACE_ID を設定する と、切り替えは上書きされる。 |
--workspace <id>、-w <id> Cloud | --workspace-id <id> | get console_app など、ワークスペース内で動作するコマンドでのみ使える。 |
get app -A、get app --all-workspaces Cloud | なし | get workspace を実行し、ワークスペースごとに get console_app --workspace-id <id> を実行する。 |
get member | get workspace member | |
create member | invite workspace member | |
set member | set workspace member_role | |
delete member | delete workspace member |
設定、difyctl スキル、ヘルプ、バージョン#
| 古いビルド | 新しいビルド | 備考 |
|---|---|---|
config get、config view、config path | get config [<key>] | 設定の保存先パスも表示する。 |
config set | set config | 残っている設定項目は http.timeout だけ。 |
config unset | unset config | |
env list | なし | difyctl が読み取る変数については、環境変数 を参照。 |
skills install | install skills <skills-root> | コーディングエージェントごとの再インストール方法は、新しいビルドへの切り替え の手順 4 を参照。 |
--short、--client、--check-compat、-o を付けた version | version | フラグを受け付けない。 |
help -o json --compact、help <command> -o json | help、help <command> | スクリプト内などでパイプした場合は JSON を出力する。 |
スクリプトのその他の更新#
JSON 形式での結果の読み取り#
結果は常に JSON で出力されるようになり、-o は不明なフラグとしてエラーになります。スクリプトから -o json を削除してください。
-o name や -o yaml など、別の形式を指定していたスクリプトでは、jq などを使って JSON を自分で整形します。チャットボットの応答だけをテキストとして取り出すには、次のようにします：
スクリプトでは DIFY_OUTPUT=json を設定するか --json を渡して、どこで実行してもエラーが JSON で出力されるようにします。設定しない場合、stderr に出力されるエラーは、パイプでは JSON、ターミナルではテキストになります。
新しい終了コードとエラーコードへの対応#
終了コードの番号はそのままですが、次の 2 つの変更があります：
- 6 は、
difyctlがサーバー上でコマンドを見つけられなかったことを表すようになりました。サーバーのコマンド一覧を取得できなかった場合と、入力した内容に一致するコマンドが一覧にない場合です。以前はバージョンの不一致を表していました。 - 64 は、
version --check-compatとともに廃止されました。
スクリプトでエラーコードによって分岐している場合は、次のように対応します：
server_4xx_otherとserver_5xxはserver_errorに置き換え、あわせて返される HTTP ステータスを確認します。token_expiredとexpired_tokenは、終了コード 4 で終了するauth_expiredに置き換えます。version_skew、unsupported_endpoint、client_error、illegal_argument、config_schema_unsupportedの分岐は削除します。
input_invalid や catalog_unavailable など、新しいコードの意味については、結果、エラー、終了コード を参照してください。
スクリプトでのリトライ#
新しいビルドは、失敗したリクエストをリトライしません。--http-retry も廃止されました。リトライを前提としていたスクリプトには、独自のリトライ処理を追加してください。どのコマンドなら安全にリトライできるかについては、失敗したコマンドのリトライ を参照してください。
環境変数の更新#
スクリプトと CI の設定から、次の環境変数を削除します：
DIFY_LIMIT：代わりに--limitを渡します。DIFYCTL_HTTP_RETRY：代替手段はありません。DIFYCTL_NO_COLOR：代わりにNO_COLORを使用します。DIFY_CACHE_DIR：キャッシュは設定フォルダに保存されるようになったため、DIFY_CONFIG_DIRだけで足ります。
DIFY_CONFIG_DIR と DIFY_WORKSPACE_ID は、これまでどおり使えます。
新しいビルドが読み取るすべての環境変数については、環境変数 を参照してください。