| 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 の例を出す必要がある場合は、比較表の左列だけに置く。 実行するコマンドとしては出さない。