# apple-container-cli-skill.md > Source: > Published: 2026-06-28 09:54:05+00:00 | 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 --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 logs --boot -n 200 ``` 統計確認では、一回だけ取得する。 ``` container stats --no-stream --format json ``` 次の操作は、実行前に対象と影響を示して確認する。 `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 inspect ` | JSON 形式で出る。 | `docker images` | `container image list` | イメージ管理は `image` サブコマンド配下にある。 | `docker pull ` | `container image pull ` | `--platform` を必要に応じて付ける。 | `docker push ` | `container image push ` | 事前に 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 ` | `container registry login ` | パスワードは `--password-stdin` を使う。 | `docker save` | `container image save --output ` | `--output` が必要である。 | `docker load -i ` | `container image load --input ` | `--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 : ``` Dockerfile の位置を指定する場合は次の形にする。 ``` container build --progress plain -f -t : ``` ビルド時引数は次の形にする。 ``` container build --progress plain --build-arg KEY=value -t : ``` マルチステージの対象を指定する場合は次の形にする。 ``` container build --progress plain --target -t : ``` Dockerfile が指定されていない場合、`container build` は `Dockerfile` を優先し、見つからなければ `Containerfile` を使う。 この探索順に依存したくない場合は、`-f` で明示する。 作業用コマンドは `--rm` を付ける。 ``` container run --rm ``` ホストの現在ディレクトリを読み書きする場合は、mount を明示する。 ``` container run --rm --mount type=bind,source="$PWD",target=/workspace -w /workspace sh -lc '' ``` 読み取り専用で足りる場合は、`readonly` を付ける。 ``` container run --rm --mount type=bind,source="$PWD",target=/workspace,readonly -w /workspace sh -lc '' ``` 環境変数は `-e` または `--env-file` で渡す。 ``` container run --rm -e NODE_ENV=test --env-file .env ``` サービスは `-d` と `--name` を使って起動する。 ``` container run -d --name -p : ``` ポート公開の形式は次のどれかにする。 ``` -p 8080:80 -p 127.0.0.1:8080:80 -p 8080:80/tcp ``` 起動後は、一覧、ログ、inspect を確認する。 ``` container list --all --format json container logs -n 200 container inspect ``` 停止と削除は分ける。 ``` container stop container delete ``` 通常は `container kill` より `container stop` を使う。 `kill` は、graceful shutdown が失敗した場合だけ使う。 非対話の exec は次の形にする。 ``` container exec ``` シェルを介して複数コマンドを実行する場合は次の形にする。 ``` container exec sh -lc '' ``` 対話シェルは、ユーザーが求めた場合だけ次の形にする。 ``` container exec -it sh ``` `container exec` の対象は稼働中コンテナに限る。 停止済みの場合は、`container start` を使うか、新しい `container run --rm` に切り替える。 `container copy` は、ホストと稼働中コンテナの間で使う。 片方は `container-id:path` の形式にする。 ホストからコンテナへコピーする。 ``` container copy ./config.json :/etc/app/config.json ``` コンテナからホストへコピーする。 ``` container copy :/var/log/app.log ./app.log ``` 対象コンテナが停止している場合は、copy ではなく export が必要か確認する。 `container export` は停止済みコンテナに使う。 稼働中コンテナには使わない。 ``` container stop container export -o ``` 標準出力へ tar を出す場合は次の形にする。 ``` container export > ``` イメージを取得する。 ``` container image pull ``` プラットフォームを指定する。 ``` container image pull --platform linux/arm64 ``` イメージにタグを付ける。 ``` container image tag ``` イメージを保存する。 ``` container image save --output ``` 保存したイメージを読み込む。 ``` container image load --input ``` レジストリへ push する前に、ログイン状態を確認する。 ``` container registry list --format json ``` ログインは標準入力でパスワードを渡す。 ``` printf '%s' "$REGISTRY_PASSWORD" | container registry login --username "$REGISTRY_USER" --password-stdin ``` 秘密情報をログに出さない。 `set -x` が有効なシェルでログインコマンドを実行しない。 名前付き volume を作る。 ``` container volume create ``` サイズを指定する。 ``` container volume create --opt size=10G ``` コンテナに接続する。 ``` container run -d --name -v : ``` volume の一覧と詳細を確認する。 ``` container volume list --format json container volume inspect ``` 匿名 volume は、`-v /path` や source なしの volume mount で作られる。 匿名 volume は UUID 風の名前を持つ。 匿名 volume は `--rm` で自動削除されない。 使い捨てコンテナでも、不要になった匿名 volume は明示的に削除する。 network コマンドは環境依存である。 使う前に存在を確認する。 ``` container network --help ``` ユーザー定義ネットワークを作る。 ``` container network create ``` コンテナをネットワークに接続して起動する。 ``` container run -d --name --network ``` ネットワークの一覧と詳細を確認する。 ``` container network list --format json container network inspect ``` ネットワーク削除は、そのネットワークを使うコンテナを停止し、削除してから実行する。 ``` container network delete ``` ビルドが失敗し、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 --cpus 4 --memory 8G --set-default alpine:3.22 ``` machine 内でコマンドを実行する。 ``` container machine run -n uname -a ``` コマンド引数が曖昧な場合は `--` を挟む。 ``` container machine run -n -- cat /proc/cpuinfo ``` コマンドなしの `container machine run` はログインシェルを開く。 非対話の Agent 実行では使わない。 machine 設定を変える。 ``` container machine set -n 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 sudo container system dns delete ``` 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 -` で起動する。 `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..image` | `container run ` に使う。 | `services..build` | 先に `container build -t -:local ` を実行する。 | `services..dockerfile` | `container build -f ` に写す。 | `services..ports` | `container run -p :` に写す。 | `services..environment` | `container run -e KEY=value` に写す。 | `services..env_file` | `container run --env-file ` に写す。 | `services..volumes` | `container run -v` または `--mount` に写す。 | `services..command` | image の後ろの arguments に置く。 | `services..entrypoint` | `container run --entrypoint ` に写す。 | `services..working_dir` | `container run -w ` に写す。 | `services..user` | `container run -u ` に写す。 | `services..cap_add` | `container run --cap-add ` に写す。 | `services..cap_drop` | `container run --cap-drop ` に写す。 | `services..networks` | `container network create` と `container run --network ` に写す。 | `services..depends_on` | 起動順としてだけ扱う。準備完了の保証とは扱わない。 | `services..restart` | 直接対応なしとして警告する。 | `services..healthcheck` | 直接対応なしとして警告する。必要なら別コマンドで確認する。 | `services..secrets` | 汎用の runtime 対応なしとして警告する。 | `services..configs` | 汎用の runtime 対応なしとして警告する。 | `services..deploy` | ローカル単体実行では直接対応なしとして警告する。 | `services..profiles` | 有効 profile を決めてから対象 service を選ぶ。 | `services..gpus` | command-reference に直接対応がなければ警告して省略する。 | `services..devices` | command-reference に直接対応がなければ警告して省略する。 | `services..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 ``` Rosetta を使う必要がある場合だけ `--rosetta` を付ける。 ``` container run --platform linux/amd64 --rosetta ``` `--rosetta` は Apple Container 固有の実行条件に関わる。 汎用 Docker フラグとして扱わない。 **サービスへ接続できない**：まず system と container の状態を見る。 ``` container system status --format json container list --all --format json container logs -n 200 container inspect ``` **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 ``` 衝突した名前を削除する前に、ユーザーへ対象を示す。 **ポートが使えない**：ホスト側の使用状況を確認する。 ``` lsof -nP -iTCP: -sTCP:LISTEN ``` 別ポートを使うか、既存プロセスを止めるかはユーザーに確認する。 **イメージ取得に失敗する**：レジストリ名、認証、platform を確認する。 ``` container registry list --format json container image pull --platform ``` **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 の例を出す必要がある場合は、比較表の左列だけに置く。 実行するコマンドとしては出さない。