floci

Floci

Floci は、実際のクラウドワイヤープロトコルに対応するローカルクラウドエミュレーターのファミリーです。 floci コマンド（floci-cli）はエミュレーターのライフサイクルを管理し、ネイティブツール（aws、gcloud、 az、oci、SDK、Terraform）がエミュレーターに対してリソース操作を行います。floci-cli 自体がクラウドリソースを 作成することはありません。

クラウド	エミュレーター	CLI ツリー	ポート	デフォルトのコンテナー	リファレンス
AWS	floci	floci aws	4566	floci	references/aws.md
GCP	floci-gcp	floci gcp	4588	floci-gcp	references/gcp.md
Azure	floci-az	floci az	4577	floci-az	references/azure.md
OCI	floci-oci	floci oci	4599	floci-oci	references/oci.md

このスキル内のすべてのパス（references/、scripts/、assets/）は、ユーザーの作業ディレクトリではなく、 このファイルが置かれているディレクトリを基準にします。

参照するタイミング：

• そのクラウドで最初のリソースコマンドを実行する前に、該当するクラウドのリファレンスを参照します。
• このセッションでまだ使用していないサービス向けのコードを書く前、および操作がサポートされていないように見える場合は、 references/docs.md を参照します。公開ドキュメントの適切なページを取得する方法が記載されています。
• ユーザーが docker run、docker-compose.yml、またはエミュレーターと通信するアプリコンテナーを希望する場合は、 references/docker.md を参照します。
• 複数のインスタンスを実行する場合、Docker ホストを共有する場合、またはコンテナーをクリーンアップする場合は、 references/namespaces.md を参照します。
• パイプラインと Testcontainers については、references/ci.md を参照します。
• 何かが失敗した場合は、references/troubleshooting.md を参照します。

前提条件（最初に確認）

command -v floci && floci version     # floci-cli present?
docker info >/dev/null && echo ok     # Docker (or Podman via DOCKER_HOST) reachable?

floci が見つからない場合は、ソフトウェアをインストールする前にユーザーに確認してから、次を実行します。

scripts/install-floci.sh                   # brew if available, else official script into ~/.local/bin
scripts/install-floci.sh --version 0.4.0   # pin a version (uses the install script)

• Windows：iwr https://floci.io/install.ps1 | iex（ユーザーごとのインストールで、管理者権限は不要です）。ここにあるヘルパースクリプトは bash 用です。Windows では、スクリプトがラップする floci コマンドを直接実行します。
• プラットフォーム用のネイティブバイナリがない場合：最新リリースから floci.jar をダウンロードして実行します （Java 25 以降が必要です）。
• 確認せずに sudo を使用したり、シェルプロファイル（~/.bashrc、~/.zshrc）を編集したりしないでください。インストール先が PATH に含まれていない場合は、現在のセッションでのみパスをエクスポートします。
• 更新：floci update --check は、最新の場合は 0、更新がある場合は 1、チェック自体に失敗した場合は 2 で終了します。終了コードが 1 の場合にのみ floci update を実行します（Homebrew でインストールした場合： brew upgrade floci）。
• ユーザーが CLI をまったく必要としない場合：エミュレーターは通常のコンテナーイメージです。references/docker.md を参照してください。

floci-cli は Docker をインストールしません。デーモンが見つからない場合はユーザーに伝えてください。自分で Docker をインストールしてはいけません。 ネイティブのクラウド CLI（aws、gcloud、az、oci）は、ユーザーが利用するクラウドの分だけ必要です。インストールを提案し、 依頼されていない限りインストールしないでください。

厳守事項

1. 実際のクラウドには絶対に接続しないでください。 エミュレーターが受け付ける偽の認証情報（AWS の場合は test／test、floci az setup と floci oci setup が作成する開発用 ID）のみを使用してください。ユーザーの実際のクラウド認証情報やプロファイルを読み取ったり、エクスポートしたり、再利用したりしないでください。
2. 変更を伴うコマンドを実行する前に、必ずエンドポイントを確認してください。 エンドポイントはエミュレーター（localhost、127.0.0.1、localhost.floci.io、または Compose のサービス名）を指している必要があります。コマンドがパブリッククラウドに接続する可能性がある場合（各リファレンスの「leaks」セクションを参照）は、いったん停止して接続設定を修正してください。
3. ツリー名は必ず明示してください。floci start ではなく、floci aws start を使用してください。ツリー名のないコマンドは floci config default-product に従うため、ユーザーが変更している可能性があります。
4. -o json で解析し、テキスト出力をスクレイピングしないでください。 スクリプトでは -q を使って余計な出力を抑えてください。
5. このセッションで自分が作成していないコンテナー、ボリューム、スナップショットは削除しないでください。 クリーンアップの対象は名前空間に限定し（namespaces.md を参照）、必ず事前にユーザーに確認してください。
6. インスタンスを --persist <dir> を指定して起動した場合、または persistDir を設定したプロファイルを使用した場合を除き、状態は一時的です。 停止中のコンテナーに対する start と restart は、コンテナーを削除して新しいコンテナーを作成します。restart では設定（ポート、イメージ、サービス、永続化ディレクトリー、名前空間）は保持されますが、メモリー上の状態は保持されません。また Azure では新しいコンテナーに新しい証明書が発行されるため、floci az setup を再実行する必要があります。実行中のコンテナーに対する start は失敗します。何かを再作成する前に、そのことを伝えてください。
7. env に -q を追加しないでください。 エクスポートそのものが抑制されます。
8. エミュレーターが何をサポートしているか推測しないでください。 記憶に頼って答えるのではなく、floci <tree> services -o json と公開ドキュメント（references/docs.md）を確認してください。
9. プロファイルを使用する場合は、env の前に起動して、起動完了を待ってください。 プロファイルのコンテナーが実行中になるまでは、env と status はデフォルトポートにフォールバックし、デフォルトのインスタンスについて説明します。reachable ではなく、status -o json の "state": "running" を信頼してください。

ライフサイクル（すべてのツリーで共通）

floci <tree> start --detach          # pull if needed, start, return immediately
floci <tree> wait --timeout 2m       # block until healthy (exit 0 = ready)
eval "$(floci <tree> env -o text)"   # export SDK/CLI wiring into this shell
# ... run aws / gcloud / az / oci / tests ...
floci <tree> stop --remove           # when done, only if you started it

プロファイルで output: json が設定されている場合も、-o text ならエクスポートを正しく取得できます。ほかのシェルでは、floci <tree> env --shell fish | source または floci <tree> env --shell powershell | Invoke-Expression を使用してください。

または、コンテナーが存在しない場合にのみ起動してから、起動完了を待ち、エクスポートを表示するヘルパーを使用してください。

exports="$(scripts/ensure-running.sh <aws|gcp|az|oci> [profile])" && eval "$exports"

この 2 つの手順は分けてください。eval "$(...)" を一度に実行すると、ヘルパーが失敗しても処理は成功し、その後のコマンドが接続設定の欠落または古い設定で実行されてしまいます。コンテナーが存在するものの停止中の場合、ヘルパーは何も変更せずに終了コード 3 で終了します。起動するとコンテナーが置き換えられるためです（ルール 6）。そのことをユーザーに伝え、同意を得てから FLOCI_REPLACE_STOPPED=1 を指定して再実行してください。

ネイティブ CLI を使用する前に、インスタンスごとに一度だけ次を実行してください。

• Azure：floci az setup（エミュレーターの証明書を信頼し、az クラウドを登録してログインします）。
• OCI：floci oci setup（使い捨てのキーと [FLOCI] プロファイルを ~/.oci/config に書き込みます）。

eval の影響は現在のシェル内に限られます。ツールを呼び出すたびに新しいシェルが起動する場合は、すべてのコマンドの前に eval "$(floci aws env -o text)" && aws s3 ls のように付けてください。

例は bash 向けです。zsh（macOS のデフォルト）では、引用符で囲まれていない変数は単語に分割されないため、flags="--profile aws-b"; floci aws status $flags は 1 つの引数として渡され、失敗します。フラグを直接記述するか、配列を使って flags=(--profile aws-b) とし、"${flags[@]}" を指定してください。

状態の確認

確認事項	コマンド
実行中で正常な状態ですか？	floci <tree> status -o json
有効になっているサービスはどれですか？	floci <tree> services -o json（Azure：空のリストが返されます。azure.md を参照してください）
CLI とサーバーのバージョン	floci <tree> version -o json（Azure：status -o json からバージョンを確認してください）
最近のサーバーログ	floci <tree> logs --tail 100 または --since 5m
環境の問題	floci <tree> doctor -o json（status が ok、warn、fail のいずれかであるチェック項目の配列です。fix を実行する前に troubleshooting.md を参照してください）
有効な設定	floci <tree> config show --profile <name>（名前空間の行は、名前空間が設定されるプロファイルでのみ表示されます）
すべてのインスタンス	floci <tree> config profile list -o json（プロファイルはすべてのツリーで共有されます。image でクラウドがわかります）。また、config profile show、edit、delete <name>
各コマンドのフラグ	floci <tree> <command> --help

複数のインスタンス

インスタンスはプロファイルです。コンテナー名が識別子となり、ポートは一意である必要があり、 Docker リソースの名前空間によって、そのインスタンスが起動するコンテナーがほかのインスタンスから分離されます。 そのインスタンスのすべてのコマンドに、同じ --profile <name> を指定してください。詳細と 名前空間の導出ルールについては、references/namespaces.md を参照してください。

floci aws config profile create aws-b --container floci-b --port 14566 --persist ~/.floci/data/aws-b
floci aws start --profile aws-b          # waits up to 30s; or --detach, then wait
eval "$(floci aws env -o text --profile aws-b)"

floci-cli は独自のファイルを ~/.floci 以下に保存します（プロファイルは ~/.floci/profiles/、インスタンスごとの 状態は ~/.floci/<product>/<container>/）。そのため、インスタンスのデータも ~/.floci/data/<name> に保存されます。

適切な連携方法の選択

• 単発のコマンドや開発サーバー：上記の CLI ライフサイクルを使用してください。
• ユーザーが docker run または Compose ファイルを求めている場合、あるいはアプリ自体がコンテナー内で動作する場合： references/docker.md を参照してください。YAML を記憶から書くのではなく、 assets/compose/ のテンプレートを基にしてください。
• コード内の統合テスト：利用可能な場合は Testcontainers モジュールを使用してください（AWS は Java、Node、 Python、Go、.NET に対応。Azure は Java のみ。GCP と OCI は非対応です。ci.md を参照してください）。それ以外の場合は、 テストの前に CLI または Compose でエミュレーターを起動してください。

サポートされていない場合

対応範囲はサービスによって異なります。完全なエンジンもあれば、プロセス内で動作するものや、定型応答を返すものもあります。サービスに対するコードを書く前に、有効になっていることを確認し （floci <tree> services -o json）、公開ドキュメント内の該当ページを参照してください （references/docs.md）。操作がサポートされていない場合は、その旨を明確に伝え、 回避策を提案し、エミュレーターの課題トラッカー （https://github.com/floci-io/<floci|floci-gcp|floci-az|floci-oci>/issues）を案内してください。コマンドのバリエーションを 再試行しないでください。