CLI reference

The boson CLI is the public local control plane. Run project commands from the project root or any nested directory; Boson discovers .boson/project.toml by walking upward.

boson create

Create a standalone workspace on infrastructure you own:

boson create my-app
boson create my-app --database-url postgres://user:pass@localhost:5432/my_app
boson create my-app --path ./products/my-app

--database-url writes the connection string into .boson/config.yaml. Boson never creates PostgreSQL. --force allows generated files to be written into a non-empty destination. boson init remains a hidden compatibility alias.

boson start

boson start

The command remains attached and performs the application startup sequence:

1. Validate build tools, project identity, ports, and configuration.
2. Build migrate, Server, and Worker packages.
3. Connect to the infrastructure declared in configuration.
4. Apply pending platform and capability migrations.
5. Start Server and Worker processes.
6. Wait for /readyz.
7. Stream prefixed logs and supervise process health.

Boson never starts or stops infrastructure. Ctrl+C gracefully stops Boson's application processes.

boson stop

boson stop

Signals the active foreground supervisor and waits up to ten seconds for graceful shutdown. If the state file is stale, Boson reconciles process state.

boson status

boson status

Reports each Boson process or local adapter's state, port, health, and version.

boson logs

boson logs
boson logs server
boson logs worker --follow

Without a service, the command prints recent Server and Worker logs. --follow streams new lines and --lines controls the initial tail (default: 100).

boson doctor

boson doctor

Checks project discovery, configuration, build tools, PostgreSQL connectivity, and the Server port. The database check opens the configured connection and runs a health query; it never creates or alters infrastructure. Failures include a concrete fix: instruction.

boson config

boson config

Prints the effective typed configuration as formatted JSON with secrets redacted.

boson deploy

boson deploy
boson deploy --tag ghcr.io/acme/my-app:0.1.0 --build
boson deploy --tag ghcr.io/acme/my-app:0.1.0 --push
boson deploy --output ./packaging

Writes packaging files (Dockerfile, .dockerignore, and CLOUD_RUN.md) to --output (default: .boson/deploy). Image names are derived from --tag (or {project}:{cli-version} when omitted) with -server, -worker, and -migrate suffixes.

--build invokes the local Docker CLI for each target. --push implies --build and pushes to the registry encoded in those tags. Plain boson deploy only writes files and does not require Docker. Boson never creates databases, buckets, mail providers, registries, IAM, or cloud services.

boson update

boson update --check
boson update

Checks the latest GitHub release. Without --check, Boson installs the matching CLI release.

Removed commands

These older commands are no longer part of the public CLI:

Removed	Replacement
boson migrate	Applied automatically by boson start
boson dev	boson start
boson admin create	Admin API / Dashboard
boson overview	Admin API /admin/v1/overview
--server / --admin-token	Removed; the CLI is no longer an Admin API client

boson config now prints the local project's redacted configuration from .boson/config.yaml. It does not call the Server Admin API.