BIANPAI(1) User Commands BIANPAI(1)

NAME

bianpai — run a Compose-compatible project on container CLIs
编排 · biānpái · ㄅㄧㄢㄆㄞˊ · "to compose, to arrange"

SYNOPSIS

bianpai [-f FILE] [-p NAME] [--backend BACKEND] COMMAND [ARGS...]

DESCRIPTION

bianpai reads a standard compose.yaml and drives it against whatever container runtime your machine actually has — no Docker daemon required. One compose file, multiple backends: wslc on Windows, Apple container on macOS, with Docker and nerdctl planned.

It is not a Compose reimplementation on top of the Docker API. Each backend translates services, networks, and volumes into invocations of the native CLI, and honestly reports what that runtime cannot do instead of pretending it can.

INSTALLATION

$ go install github.com/bianpai/bianpai@latest

Or build from source:

$ git clone https://github.com/bianpai/bianpai.git
$ cd bianpai
$ go build -o bianpai .

Requires Go ≥ 1.26. No runtime dependencies beyond your container CLI.

COMMANDS

up [SERVICE...]: Create networks and volumes, then (re)create and start containers.
-d, --detach run in the background · --build build images first

Foreground attach is not implemented yet; up always runs detached.
down: Stop and remove project containers and networks.
-v, --volumes also remove named volumes
ps: List project containers.
logs [SERVICE...]: Show service logs.
--follow stream logs live
build [SERVICE...]: Build service images.
--no-cache · --pull always pull newer base images
pull [SERVICE...]: Pull service images. Services with a build: section are skipped.
exec SERVICE COMMAND...: Run a command inside a running service container.
version: Show backend version information.

OPTIONS

-f, --file FILE: Compose file path. Defaults to compose-file discovery in the working directory.
-p, --project-name NAME: Project name. Defaults to the compose file's directory name.
--backend BACKEND: Container backend: wslc or container. Platform-aware default: wslc on Windows, container on macOS; other platforms must pass it explicitly.

BACKENDS

	wslc	container	docker	nerdctl
status	✓ shipped	✓ shipped	planned	planned
platform	Windows	macOS	—	—
service DNS	✓	✗ rejected	—	—
network aliases	✓	✗	—	—
bind mounts	✓ Windows paths	✓	—	—
named volumes	✓	✓ shareable	—	—
isolation	namespaces	one VM per container	—	—

wslc (Windows) — drives the WSLC CLI that ships with WSL (verified against wslc 2.9.x). Supports the full Compose networking model: services on a shared network resolve each other by name (db, api, etcd2), aliases and hostname: work, and relative bind-mount paths resolve to C:\... host paths with live changes visible inside the container.

container (macOS) — drives Apple's container CLI, which boots each container in its own lightweight Linux VM. Volumes are fully shareable and bridge networks give raw-IP connectivity, but there is no service-name DNS between VMs; projects that require it are rejected with a clear limitation message rather than started half-broken.

On every backend, keys with no native equivalent — restart:, privileged:, network_mode:, extra_hosts:, healthcheck-gated depends_on: — surface as warnings, never as silent no-ops.

EXAMPLES

Bring up a project with the platform default backend:

$ bianpai up -d
Network myapp_default Created
Volume myapp_pgdata Created
Container myapp_db_1 Started
Container myapp_api_1 Started

Force a specific backend:

$ bianpai --backend container up -d

Follow one service's logs, poke around inside another:

$ bianpai logs --follow api
$ bianpai exec db psql -U postgres

Tear everything down, volumes included:

$ bianpai down -v

CONVENTIONS

Resources are named project_service_1 (containers), project_network and project_volume, and every created object is labeled com.bianpai.project / com.bianpai.service so backends can find their own state.