CLI Reference
Complete reference for all 52 Docker-compatible CLI commands
CLI Reference
A3S Box provides a Docker-compatible CLI with 52 commands. Boxes can be referenced by full ID, 12-character short ID prefix, or name.
Lifecycle Management
run
Pull, create, and start a box in one command.
a3s-box run [OPTIONS] IMAGE [-- COMMAND [ARGS...]]Common flags:
Prop
Type
Examples:
# Interactive shell
a3s-box run -it alpine:latest -- /bin/sh
# Detached with resource limits
a3s-box run -d --name web --cpus 4 --memory 2g nginx:alpine
# With health check and restart policy
a3s-box run -d --name api \
--health-cmd "curl -f http://localhost:8080/health" \
--health-interval 10 \
--restart on-failure:3 \
my-api:latest
# With security options
a3s-box run -d --cap-drop ALL --cap-add NET_BIND_SERVICE \
--security-opt seccomp=default --read-only nginx:alpine
# TEE simulation
a3s-box run -d --name secure --tee --tee-simulate alpine:latest -- sleep 3600create
Create a box without starting it. Accepts the same flags as run.
a3s-box create [OPTIONS] IMAGE [-- COMMAND [ARGS...]]start / stop / restart
a3s-box start BOX [BOX...]
a3s-box stop BOX [BOX...]
a3s-box restart BOX [BOX...]kill
Force-terminate a box with a signal.
a3s-box kill BOX [BOX...]rm
a3s-box rm [OPTIONS] BOX [BOX...]Prop
Type
pause / unpause
Suspend and resume a box (SIGSTOP / SIGCONT).
a3s-box pause BOX
a3s-box unpause BOXrename
a3s-box rename BOX NEW_NAMEwait
Block until boxes stop and print their exit codes.
a3s-box wait BOX [BOX...]container-update
Hot-update resource limits of a running box.
a3s-box container-update BOX [OPTIONS]Prop
Type
Execution and Terminal
exec
Run a command inside a running box.
a3s-box exec [OPTIONS] BOX -- COMMAND [ARGS...]Prop
Type
# Interactive shell
a3s-box exec -it my-box -- /bin/bash
# Run as root with env var
a3s-box exec -u root -e DEBUG=1 my-box -- /bin/sh -c "env"attach
Attach to a box's console.
a3s-box attach [-it] BOXtop
Show processes running inside a box.
a3s-box top BOXImage Management
pull
a3s-box pull [OPTIONS] IMAGEProp
Type
a3s-box pull alpine:latest
a3s-box pull --verify-key cosign.pub ghcr.io/my-org/my-image:v1
a3s-box pull --verify-issuer https://accounts.google.com \
--verify-identity user@example.com my-image:latestpush
a3s-box push IMAGEbuild
Build an OCI image from a Dockerfile.
a3s-box build [OPTIONS] PATHProp
Type
# Single platform
a3s-box build -t my-app:v1 .
# Multi-platform image index
a3s-box build -t my-app:v1 --platform linux/amd64,linux/arm64 .
# With build args
a3s-box build -t my-app:v1 --build-arg VERSION=1.2.3 -f Dockerfile.prod .images
a3s-box images [OPTIONS]Prop
Type
rmi
a3s-box rmi IMAGE [IMAGE...]tag
a3s-box tag SOURCE TARGETimage-inspect
Show image metadata as JSON.
a3s-box image-inspect IMAGEimage-prune
Remove unused images.
a3s-box image-prunehistory
Show image layer history.
a3s-box history IMAGEsave / load
a3s-box save IMAGE -o FILE.tar
a3s-box load -i FILE.tarcommit
Create a new image from a box's filesystem changes.
a3s-box commit [OPTIONS] BOX IMAGE:TAGProp
Type
export
Export a box's filesystem as a tar archive.
a3s-box export BOX -o FILE.tarInspection and Monitoring
ps
a3s-box ps [OPTIONS]Prop
Type
a3s-box ps -a --filter status=running
a3s-box ps --format "{{.ID}}\t{{.Name}}\t{{.Status}}"inspect
Show detailed box information as JSON.
a3s-box inspect BOXlogs
a3s-box logs [OPTIONS] BOXProp
Type
stats
Live resource usage for running boxes.
a3s-box stats [BOX...]Displays CPU %, memory usage, and disk I/O.
events
Stream system events.
a3s-box events [OPTIONS]Prop
Type
diff
Show filesystem changes in a box (A=added, C=changed, D=deleted).
a3s-box diff BOXport
List port mappings for a box.
a3s-box port BOXdf
Show disk usage.
a3s-box dfNetworking
network create
a3s-box network create [OPTIONS] NAMEProp
Type
network ls / inspect / rm
a3s-box network ls
a3s-box network inspect NAME
a3s-box network rm NAMEnetwork connect / disconnect
a3s-box network connect NETWORK BOX
a3s-box network disconnect NETWORK BOXVolumes
volume create / ls / inspect / rm / prune
a3s-box volume create NAME
a3s-box volume ls
a3s-box volume inspect NAME
a3s-box volume rm NAME
a3s-box volume pruneFile Operations
cp
Copy files between host and box. Copying between two boxes is not supported.
a3s-box cp BOX:SRC_PATH DEST_PATH # box → host
a3s-box cp SRC_PATH BOX:DEST_PATH # host → boxSnapshots
snapshot create / restore / ls / rm / inspect
a3s-box snapshot create BOX NAME
a3s-box snapshot restore BOX NAME
a3s-box snapshot ls BOX
a3s-box snapshot rm BOX NAME
a3s-box snapshot inspect BOX NAMECompose
compose up / down / ps / config
a3s-box compose up [-f FILE] [-d]
a3s-box compose down [-f FILE]
a3s-box compose ps [-f FILE]
a3s-box compose config [-f FILE]Default compose file: compose.yaml or docker-compose.yaml in the current directory.
TEE / Security
attest
Request a TEE attestation report from a running box.
a3s-box attest BOX [OPTIONS]Prop
Type
seal / unseal
a3s-box seal BOX --data "DATA" --context CTX [--policy POLICY] [--allow-simulated]
a3s-box unseal BOX --context CTX [--allow-simulated]Prop
Type
inject-secret
Inject a secret into a running TEE-protected box over RA-TLS.
a3s-box inject-secret BOX --secret "KEY=VALUE" [--set-env] [--allow-simulated]Secret is written to /run/secrets/KEY (mode 0400). --set-env also sets it as an environment variable.
Audit
audit
Query the persistent audit log.
a3s-box audit [OPTIONS]Prop
Type
System
system-prune
Remove stopped boxes and unused images.
a3s-box system-prune [-f]monitor
Background daemon that auto-restarts boxes with restart=always or restart=on-failure.
a3s-box monitorversion / info / df
a3s-box version # Show version
a3s-box info # System information
a3s-box df # Disk usagelogin / logout
a3s-box login REGISTRY [-u USERNAME] [--password-stdin]
a3s-box logout REGISTRYCredentials stored in ~/.a3s/auth.json.
Box Identification
Boxes can be referenced by:
Prop
Type