apple-container-cli-skill.md

Apple Container の container CLI を安全に操作するための Skill が公開された。Docker CLI 互換を仮定せず、公式 command-reference に基づきビルド、実行、ログ、exec、copy、image、volume、network、registry、builder、machine、system を扱う。Docker Compose 風の依頼を単体コマンド列へ分解する際にも使用される。

| name | apple-container-cli | |---|---| | description | Apple Container の container CLI を Agent が安全に操作するための Skill。Docker CLI 互換だと仮定せず、公式 command-reference にある container サブコマンドを使い、ビルド、実行、ログ、exec、copy、image、volume、network、registry、builder、machine、system を扱う。Docker Compose 風の依頼を単体コマンド列へ分解するときにも使用する。 | Apple Container の container CLI を使う作業では、この Skill に従う。 container は Docker CLI ではない。 Docker のコマンド名、Docker Engine API、Docker Compose の存在を仮定しない。 OCI イメージを扱う点は共通しているが、操作では container のサブコマンドを直接選ぶ。 - Apple Container でコンテナを起動する。 - Apple Container でイメージをビルド、取得、保存、配布する。 - Apple Container のログ、状態、ファイルコピー、exec、統計を扱う。 - Apple Container の volume、network、registry、builder、machine、system を扱う。 - Docker コマンドで依頼された作業を Apple Container のコマンドに読み替える。 docker-compose.yml や compose.yml の内容を、Apple Container の単体コマンド列へ分解する。 docker ではなく container を使う。 docker compose ではなく、必要な container build 、 container network 、 container volume 、 container run に分解する。 container のローカル実装を最終的な根拠にする。- 公式ドキュメントと実行環境が食い違う場合は、 container <command --help の結果を優先する。 - スクリプトでは短縮エイリアスより正式名を使う。 - 取得や確認では、利用できる限り --format json を使う。 - 非対話の Agent 実行では、終了しないコマンドを避ける。 - ホストを変更する操作は、変更範囲を説明してから実行する。 作業前に、ローカル環境と Apple Container の状態を確認する。 command -v container sw vers -productVersion uname -m container system version --format json || container system version container system status --format json || container system status container が見つからない場合は、Docker で代替しない。 Apple Container が未導入であると報告し、インストールが必要だと伝える。 uname -m が arm64 でない場合は、Apple Silicon 前提を満たしていない可能性を報告する。 そのまま Docker や別ランタイムへ切り替えない。 container system status がサービス停止を示す場合は、ユーザーが初期化や起動を依頼しているときだけ次を実行する。 container system start container system start はホストのサービスを起動する。 未確認のまま、診断のつもりで実行しない。 次の場合は、実行前に help を見る。 container --help container run --help container build --help container image --help container volume --help container network --help container machine --help container system --help - ドキュメントにあるはずのコマンドが失敗した。 - ユーザーの環境が古い、または新しい可能性がある。 network 、 machine 、 system kernel のように macOS やバージョンの影響を受けやすいコマンドを使う。- Docker Compose 風の依頼を Apple Container へ変換する。 - 未確認のフラグを使いたくなった。 help で存在を確認できないコマンドやフラグは使わない。 Agent が自動実行するときは、次の規則に従う。 - 長く動くサービスは container run -d で起動する。 - 一回だけ実行する処理は container run --rm を使う。 container run -it は、ユーザーが対話シェルを求めた場合だけ使う。 container exec -it は、ユーザーが対話操作を求めた場合だけ使う。 container logs --follow は、ユーザーが追跡表示を求めた場合だけ使う。 container stats は、非対話では必ず --no-stream を付ける。 container machine run をコマンドなしで実行しない。 container start --attach --interactive は、対話を求められた場合だけ使う。- レジストリのパスワードはコマンドライン引数に置かず、 --password-stdin を使う。 ログ確認では、既定で直近の行数を絞る。 container logs -n 200 <container-id container logs --boot -n 200 <container-id 統計確認では、一回だけ取得する。 container stats --no-stream --format json <container-id 次の操作は、実行前に対象と影響を示して確認する。 container delete --all container delete --force container prune container image delete --all container image prune --all container volume delete --all container volume prune container network delete --all container network prune container builder delete --force container machine delete container system stop container system dns create container system dns delete container system kernel set 名前で範囲を限定できる場合は、 --all を使わない。 --force は、通常停止や通常削除に失敗した場合だけ使う。 | Docker での意図 | Apple Container で使うコマンド | 注意 | |---|---|---| docker ps | container list | 既定では稼働中だけを表示する。 | docker ps -a | container list --all | 停止済みも含める。 | docker inspect <container | container inspect <container | JSON 形式で出る。 | docker images | container image list | イメージ管理は image サブコマンド配下にある。 | docker pull <image | container image pull <image | --platform を必要に応じて付ける。 | docker push <image | container image push <image | 事前に registry login を確認する。 | docker build -t app . | container build -t app . | Dockerfile がなければ Containerfile を探す。 | docker run ... | container run ... | Docker 専用フラグを混ぜない。 | docker exec ... | container exec ... | 対象コンテナは稼働中である必要がある。 | docker logs ... | container logs ... | 既定で全ログを出し得るため -n を使う。 | docker cp ... | container copy ... | スクリプトでは copy を使う。 | docker stop ... | container stop ... | --time と --signal を使える。 | docker rm ... | container delete ... | スクリプトでは delete を使う。 | docker rmi ... | container image delete ... | 稼働中コンテナが参照するイメージは先にコンテナを処理する。 | docker volume ls | container volume list | 永続 volume は volume サブコマンド配下にある。 | docker network ls | container network list | network は環境によって使えない場合がある。 | docker login <registry | container registry login <registry | パスワードは --password-stdin を使う。 | docker save | container image save --output <file <image | --output が必要である。 | docker load -i <file | container image load --input <file | --input が必要である。 | docker stats --no-stream | container stats --no-stream | 非対話では --no-stream を必ず使う。 | docker system df | container system df | JSON 出力を使える。 | docker compose ... | 直接対応なしとして扱う | ローカル help で確認できない限り container compose を使わない。 | Apple Container の通常操作では、次のサブコマンドだけを候補にする。 Core ： container run 、 container build 。 Container ： container create 、 container start 、 container stop 、 container kill 、 container delete 、 container list 、 container exec 、 container export 、 container logs 、 container inspect 、 container stats 、 container copy 、 container prune 。 Image ： container image list 、 container image pull 、 container image push 、 container image save 、 container image load 、 container image tag 、 container image delete 、 container image prune 、 container image inspect 。 Builder ： container builder start 、 container builder status 、 container builder stop 、 container builder delete 。 Network ： container network create 、 container network delete 、 container network prune 、 container network list 、 container network inspect 。 Volume ： container volume create 、 container volume delete 、 container volume prune 、 container volume list 、 container volume inspect 。 Registry ： container registry login 、 container registry logout 、 container registry list 。 Machine ： container machine create 、 container machine run 、 container machine list 、 container machine inspect 、 container machine set 、 container machine set-default 、 container machine logs 、 container machine stop 、 container machine delete 。 System ： container system start 、 container system stop 、 container system status 、 container system version 、 container system logs 、 container system df 、 container system dns create 、 container system dns delete 、 container system dns list 、 container system kernel set 、 container system property list 。 エイリアスの ls 、 rm 、 cp 、 m は、手入力では使ってよい。 Agent が保存する手順やスクリプトでは、正式名を使う。 通常のビルドは次の形にする。 container build --progress plain -t <image-name :<tag <context-dir Dockerfile の位置を指定する場合は次の形にする。 container build --progress plain -f <dockerfile-path -t <image-name :<tag <context-dir ビルド時引数は次の形にする。 container build --progress plain --build-arg KEY=value -t <image-name :<tag <context-dir マルチステージの対象を指定する場合は次の形にする。 container build --progress plain --target <stage -t <image-name :<tag <context-dir Dockerfile が指定されていない場合、 container build は Dockerfile を優先し、見つからなければ Containerfile を使う。 この探索順に依存したくない場合は、 -f で明示する。 作業用コマンドは --rm を付ける。 container run --rm <image <command <args ホストの現在ディレクトリを読み書きする場合は、mount を明示する。 container run --rm --mount type=bind,source="$PWD",target=/workspace -w /workspace <image sh -lc '<command ' 読み取り専用で足りる場合は、 readonly を付ける。 container run --rm --mount type=bind,source="$PWD",target=/workspace,readonly -w /workspace <image sh -lc '<command ' 環境変数は -e または --env-file で渡す。 container run --rm -e NODE ENV=test --env-file .env <image <command サービスは -d と --name を使って起動する。 container run -d --name <name -p <host-port :<container-port <image ポート公開の形式は次のどれかにする。 -p 8080:80 -p 127.0.0.1:8080:80 -p 8080:80/tcp 起動後は、一覧、ログ、inspect を確認する。 container list --all --format json container logs -n 200 <name container inspect <name 停止と削除は分ける。 container stop <name container delete <name 通常は container kill より container stop を使う。 kill は、graceful shutdown が失敗した場合だけ使う。 非対話の exec は次の形にする。 container exec <container-id <command <args シェルを介して複数コマンドを実行する場合は次の形にする。 container exec <container-id sh -lc '<command ' 対話シェルは、ユーザーが求めた場合だけ次の形にする。 container exec -it <container-id sh container exec の対象は稼働中コンテナに限る。 停止済みの場合は、 container start を使うか、新しい container run --rm に切り替える。 container copy は、ホストと稼働中コンテナの間で使う。 片方は container-id:path の形式にする。 ホストからコンテナへコピーする。 container copy ./config.json <container-id :/etc/app/config.json コンテナからホストへコピーする。 container copy <container-id :/var/log/app.log ./app.log 対象コンテナが停止している場合は、copy ではなく export が必要か確認する。 container export は停止済みコンテナに使う。 稼働中コンテナには使わない。 container stop <container-id container export -o <output.tar <container-id 標準出力へ tar を出す場合は次の形にする。 container export <container-id <output.tar イメージを取得する。 container image pull <image プラットフォームを指定する。 container image pull --platform linux/arm64 <image イメージにタグを付ける。 container image tag <source <target イメージを保存する。 container image save --output <image.tar <image 保存したイメージを読み込む。 container image load --input <image.tar レジストリへ push する前に、ログイン状態を確認する。 container registry list --format json ログインは標準入力でパスワードを渡す。 printf '%s' "$REGISTRY PASSWORD" | container registry login --username "$REGISTRY USER" --password-stdin <registry 秘密情報をログに出さない。 set -x が有効なシェルでログインコマンドを実行しない。 名前付き volume を作る。 container volume create <volume-name サイズを指定する。 container volume create --opt size=10G <volume-name コンテナに接続する。 container run -d --name <name -v <volume-name :<path-in-container <image volume の一覧と詳細を確認する。 container volume list --format json container volume inspect <volume-name 匿名 volume は、 -v /path や source なしの volume mount で作られる。 匿名 volume は UUID 風の名前を持つ。 匿名 volume は --rm で自動削除されない。 使い捨てコンテナでも、不要になった匿名 volume は明示的に削除する。 network コマンドは環境依存である。 使う前に存在を確認する。 container network --help ユーザー定義ネットワークを作る。 container network create <network-name コンテナをネットワークに接続して起動する。 container run -d --name <name --network <network-name <image ネットワークの一覧と詳細を確認する。 container network list --format json container network inspect <network-name ネットワーク削除は、そのネットワークを使うコンテナを停止し、削除してから実行する。 container network delete <network-name ビルドが失敗し、builder の状態が疑わしい場合は status を見る。 container builder status --format json builder を明示的に起動する場合は、必要な資源を指定する。 container builder start --cpus 2 --memory 2048M builder を停止する。 container builder stop builder の削除は、ビルド環境を作り直す意図がある場合だけ行う。 container builder delete container machine は、コンテナを動かすための machine を扱う。 m エイリアスは使わず、正式名を書く。 machine 一覧を見る。 container machine list --format json 既定の machine を inspect する。 container machine inspect machine を作る。 container machine create --name <machine-name --cpus 4 --memory 8G --set-default alpine:3.22 machine 内でコマンドを実行する。 container machine run -n <machine-name uname -a コマンド引数が曖昧な場合は -- を挟む。 container machine run -n <machine-name -- cat /proc/cpuinfo コマンドなしの container machine run はログインシェルを開く。 非対話の Agent 実行では使わない。 machine 設定を変える。 container machine set -n <machine-name cpus=4 memory=8G 設定変更は、machine の停止と再起動後に効く。 その場で効いたと仮定しない。 system の状態を見る。 container system status --format json バージョンを見る。 container system version --format json サービスログを見る。 container system logs --last 10m ディスク使用量を見る。 container system df --format json プロパティを見る。 container system property list --format json DNS ドメインの作成と削除には管理者権限が必要である。 Agent は sudo を勝手に使わない。 ユーザーが明示的に許可した場合だけ実行する。 sudo container system dns create <domain-name sudo container system dns delete <domain-name kernel の設定はホストの実行基盤に影響する。 ユーザーが明示的に要求した場合だけ実行する。 container system kernel set --recommended docker-compose.yml 、 compose.yml 、 compose.yaml がある場合でも、 container compose を当然のように使わない。 まずローカル help を確認する。 container --help container compose が help に出ない場合は、Compose ファイルを読み、Apple Container の単体コマンド列に分解する。 分解は次の順に行う。 - プロジェクト名を決める。 services を列挙する。 build がある service のイメージ名を決め、 container build を作る。 volumes の名前付き volume を container volume create で作る。 networks のユーザー定義 network を container network create で作る。 depends on を起動順として扱う。- 各 service を container run -d --name <project -<service で起動する。 ports 、 environment 、 env file 、 volumes 、 command 、 entrypoint 、 cap add 、 cap drop を対応する run フラグへ写す。- Apple Container の command-reference に直接対応がないキーは、実行前に警告して省略する。 - 起動後に container list --all --format json と container logs -n 200 で状態を確認する。 Compose 風の主な対応は次の通りである。 | Compose の項目 | Apple Container での扱い | |---|---| services.<name .image | container run <image に使う。 | services.<name .build | 先に container build -t <project -<service :local <context を実行する。 | services.<name .dockerfile | container build -f <path に写す。 | services.<name .ports | container run -p <host :<container に写す。 | services.<name .environment | container run -e KEY=value に写す。 | services.<name .env file | container run --env-file <file に写す。 | services.<name .volumes | container run -v または --mount に写す。 | services.<name .command | image の後ろの arguments に置く。 | services.<name .entrypoint | container run --entrypoint <cmd に写す。 | services.<name .working dir | container run -w <dir に写す。 | services.<name .user | container run -u <user に写す。 | services.<name .cap add | container run --cap-add <cap に写す。 | services.<name .cap drop | container run --cap-drop <cap に写す。 | services.<name .networks | container network create と container run --network <name に写す。 | services.<name .depends on | 起動順としてだけ扱う。準備完了の保証とは扱わない。 | services.<name .restart | 直接対応なしとして警告する。 | services.<name .healthcheck | 直接対応なしとして警告する。必要なら別コマンドで確認する。 | services.<name .secrets | 汎用の runtime 対応なしとして警告する。 | services.<name .configs | 汎用の runtime 対応なしとして警告する。 | services.<name .deploy | ローカル単体実行では直接対応なしとして警告する。 | services.<name .profiles | 有効 profile を決めてから対象 service を選ぶ。 | services.<name .gpus | command-reference に直接対応がなければ警告して省略する。 | services.<name .devices | command-reference に直接対応がなければ警告して省略する。 | services.<name .privileged | command-reference に直接対応がなければ警告して省略する。 | 対応が不明なキーを、似た名前の Docker フラグに推測変換しない。 未対応項目は一覧にして、実行したコマンドとは分けて報告する。 この例は、Compose ファイルを読み替えるときの形を示す。 実際の service 名、ポート、volume、環境変数は、対象ファイルから取る。 set -euo pipefail PROJECT=myapp container network create "${PROJECT}-default" || true container volume create "${PROJECT}-data" || true container build --progress plain -t "${PROJECT}-web:local" ./web container run -d \ --name "${PROJECT}-db" \ --network "${PROJECT}-default" \ -v "${PROJECT}-data:/var/lib/app" \ -e APP ENV=local \ example-db:latest container run -d \ --name "${PROJECT}-web" \ --network "${PROJECT}-default" \ -p 8080:80 \ -e DATABASE HOST="${PROJECT}-db" \ "${PROJECT}-web:local" container list --all --format json container logs -n 200 "${PROJECT}-web" || true は、既存の network や volume を再利用する意図が明確な場合だけ使う。 既存リソースの再利用が危険な場合は、先に inspect して中身を確認する。 Apple Silicon 上で amd64 イメージを扱う場合は、まず platform を明示する。 container run --platform linux/amd64 <image <command Rosetta を使う必要がある場合だけ --rosetta を付ける。 container run --platform linux/amd64 --rosetta <image <command --rosetta は Apple Container 固有の実行条件に関わる。 汎用 Docker フラグとして扱わない。 サービスへ接続できない ：まず system と container の状態を見る。 container system status --format json container list --all --format json container logs -n 200 <container-id container inspect <container-id API サーバーが応答しない ：system logs と version を見る。 container system logs --last 10m container system version --format json || container system version ビルドが止まる、または builder が怪しい ：builder の状態を見る。 container builder status --format json 必要があれば builder を起動する。 container builder start --cpus 2 --memory 2048M 名前が衝突する ：既存コンテナを確認する。 container list --all --format json container inspect <name 衝突した名前を削除する前に、ユーザーへ対象を示す。 ポートが使えない ：ホスト側の使用状況を確認する。 lsof -nP -iTCP:<host-port -sTCP:LISTEN 別ポートを使うか、既存プロセスを止めるかはユーザーに確認する。 イメージ取得に失敗する ：レジストリ名、認証、platform を確認する。 container registry list --format json container image pull --platform <platform <image copy が失敗する ：対象コンテナが稼働中か確認する。 container list --all --format json 停止済みコンテナから丸ごと取り出す必要がある場合は、 container export を検討する。 volume が残る ：匿名 volume と参照状態を確認する。 container volume list --format json container system df --format json 匿名 volume は --rm で消えない。 不要なら対象名を確認してから削除する。 作業後は、次の情報を短く報告する。 - 実行した主な container コマンド。 - 作成または変更したコンテナ、イメージ、volume、network、machine。 - 公開したポート。 - 稼働状態。 - 省略した Compose 項目や未対応フラグ。 - 後始末に使うコマンド。 作業に失敗した場合は、失敗したコマンド、終了コード、関連ログ、次に試す最小の診断コマンドを示す。 Docker へ切り替えたかのように報告しない。 ユーザーへ提示するコマンドは、コピーして実行できる形にする。 よい例は次の形である。 container run -d --name web -p 8080:80 nginx:latest container logs -n 200 web 避ける例は次の形である。 docker run -d --name web -p 8080:80 nginx:latest container compose up -d container stats web container logs -f web Docker の例を出す必要がある場合は、比較表の左列だけに置く。 実行するコマンドとしては出さない。