Bizone CLI

An assistant CLI for running the Bizone orchestrator platform locally using Docker.

The CLI starts, configures, and stops the platform containers — a bundled mysql database, resource-manager, orchestrator, state-store, and ui — plus the one-shot resources initialization job (bizone-resources). Optionally runs cloud-tools as well if required. Works on macOS and Windows.

Installation

Requires Node.js >= 18 and a running Docker engine.

Run without installing (npx)

Run the latest published version directly — no install step:

npx @bizone-ai/cli start
# e.g.
# npx @bizone-ai/cli <category> <command> [args]

Global install (recommended)

Install the published package globally so the bizone command is on your PATH:

npm install -g @bizone-ai/cli
bizone --version

From source (local clone)

cd cli
npm install        # no runtime dependencies, but sets up the bin link
npm link           # makes `bizone` available globally (optional)

Or run directly without linking:

node cli/bin/bizone.js <category> <command> [args]

All examples below assume the bizone command is on your PATH (via global install, npm link, or npx @bizone-ai/cli).

Command structure

bizone <category> <command> [args] [--no-colors]

| Category | Aliases | Purpose | |-----------------|-------------|-------------------------------------------------| | start | — | Start the platform | | stop | — | Stop the platform | | configuration | config,c| General CLI configuration | | images | img | Override image URLs / add custom services | | environment | env | Set environment variables per container | | resources | res, r | Resources imported into the resource-manager | | database | db | Manage the bundled MySQL database |

Global flags:

• --no-colors — disable ANSI colors (also disabled when NO_COLOR is set or output is not a TTY)
• --help, -h — show usage
• --version, -v — show version

Configuration file

All settings are stored in a single JSON file in your home directory:

• macOS / Linux: ~/.bizone/config.json
• Windows: %USERPROFILE%\.bizone\config.json

Running container ids are tracked alongside it in containers.json.

File shape:

{
  "config":    { "key": "value" },
  "images":    { "type": "image-url" },
  "env":       { "type": { "NAME": "value" } },
  "resources": { "namespace": "path" },
  "custom":    { "id": "path-to-service.json" }
}

configuration — general settings

bizone config get                 # show current configuration (with defaults)
bizone config set {key} {value}   # set a config key
bizone config remove {key}        # reset a key back to its default

Stored at $.config.{key}.

Available keys

| Key | Default | Description | |-------------------------|----------------|----------------------------------------------------------------------------------------------------| | forward_aws_env | true | Forward AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY into the orchestrator container | | aws_profile | (empty) | AWS named profile used for ECR auto-login (aws ... --profile {profile}); empty = default profile | | network_name | bizone-local | Shared docker network all containers join | | mysql_port | 33306 | Host port for the bundled MySQL database | | orchestrator_port | 8001 | Host port for the orchestrator | | resource_manager_port | 7070 | Host port for the resource-manager | | state_store_port | 8088 | Host port for the state-store | | state_store_enable | true | Run state-store as part of the sequence | | cloud_tools_port | 8086 | Host port for cloud-tools | | cloud_tools_enable | false | Run cloud-tools as part of the sequence | | ui_port | 7006 | Host port for the UI | | timeout_sec | 300 | Readiness wait timeout per service (seconds) |

Example:

bizone config set ui_port 9006
bizone config set cloud_tools_enable true

images — override container images

bizone images get                 # list image URLs + custom services
bizone images set {type} {url}    # override an image
bizone images remove {type|id}    # reset an image, or unregister a custom service
bizone images add {id} {path}     # register an additional custom service

Stored at $.images.{type}. Valid types:

mysql, orchestrator, state-store, resource-manager, cloud-tools, ui, resources

Example:

bizone images set state-store bizone-local/state-store:1.0.0

Additional custom services (images add)

Register extra services that aren't part of the built-in topology. Each is identified by an {id} and points to a JSON file describing the service, using the same shape as the built-in service objects (see src/containers/mysql.js):

bizone images add {id} {path-to-service.json}    # register / update
bizone images remove {id}                        # unregister

Stored at $.custom.{id}. The JSON file shape:

{
  "type": "redis",
  "image": "redis:7",
  "containerName": "bizone-redis",
  "containerPort": 6379,
  "portKey": "redis_port",
  "defaultPort": "6379",
  "enableKey": null,
  "readyPath": "/.system/status",
  "readyCheck": "systemStatusOk",
  "volume": { "name": "bizone-redis-data", "mount": "/data" },
  "defaultEnv": { "SOME_VAR": "value" }
}

• image and containerName are required; everything else is optional.
• containerName should start with bizone- (so db destroy recognizes it) and must not collide with a built-in container.
• type defaults to the {id} if omitted; it is the key for image/env overrides (bizone env set {type} ...).
• readyCheck (optional) must be one of systemStatusOk, uiReadinessUp, mysqlPing. With systemStatusOk/uiReadinessUp the CLI polls http://localhost:{port}{readyPath}; with mysqlPing it uses mysqladmin ping. Omit both readyPath and readyCheck to skip the readiness wait.
• enableKey (optional) — a config key gating the service. Omit / null to always run.

Custom services are validated when added (the CLI parses the file immediately). They start last, after the built-in platform is ready, and are stopped by bizone stop like any other container. Relative {path} values resolve against the .bizone config directory.

Example:

bizone images add redis ./redis.json
bizone start          # built-ins first, then redis
bizone images get     # redis shown under "Custom services"

environment — per-container environment variables

bizone env get {type}                 # show env vars (secrets masked)
bizone env set {type} {name} {value}  # set an env var
bizone env remove {type} {name}       # remove an env var

Stored at $.env.{type}.{name}. {type} is one of the image types above.

Each container type also has built-in default environment variables that are applied at run time unless you override the same key with env set (your value wins). env get shows the effective set, tagging each entry as (default) or (override). For example, the MySQL client defaults (storage.type=mysql, mysql.storage, mysql.storage.user, mysql.storage.password.secret, secret.mysql.password) are applied to every container except ui, and the mysql container gets MYSQL_ROOT_PASSWORD=root.

Secret values are masked on get (showing only the first 4 and last 4 characters). Keys are treated as secrets when they match a predefined list (e.g. AWS_SECRET_ACCESS_KEY, mysql.storage.password.secret) or contain password / secret / token / apikey.

Example:

bizone env set state-store db_url "mysql://user:pass@host:3306/db"
bizone env get state-store
#   db_url = mysq*******...****/db

These env vars are passed to the container at run time via -e NAME=value.

resources — startup resource import

Define resources to import into the resource-manager on startup, grouped by namespace.

bizone resources get                       # list configured sources
bizone resources set {namespace} {path}    # set a file or folder source
bizone resources remove {namespace}        # remove a namespace source
bizone resources import [global]           # import now (see below)

Stored at $.resources.{namespace}. {path} may be:

• a folder — every .json file found recursively becomes one item
• a single file with an items array — that array is used as the items
• a single file otherwise — the whole file becomes the only item

Relative paths resolve against the .bizone config directory.

Example:

bizone resources set my_namespace ./my_namespace.json

Import procedure

On startup, for each namespace, the CLI sends:

POST http://localhost:{resource_manager_port}/admin/{namespace}/status

{ "user": "bizone-cli", "message": "resource initialization", "items": [ ... ] }

resources import — import on demand

Run an import against the already-running platform (resource-manager must be up):

bizone resources import          # import the user-configured namespaces (above)
bizone resources import global   # run ONLY the bizone-resources job (core resources)

• Without global: imports the namespaces configured via resources set.
• With global: runs the one-shot bizone-resources docker job, which imports the core resources into the .global namespace. This is the same job bizone start runs (unconditionally here — used to (re)seed core resources).

start — start the platform

bizone start

Non-blocking: once everything is ready it prints "Platform is running" and returns control to the shell. Container ids are saved to ~/.bizone/containers.json keyed by container name.

Startup sequence

1. Create the shared docker network bizone-local (skipped if it exists).

2. Start mysql only if it is not already running (an existing DB container is reused), then wait until it accepts connections (mysqladmin ping). The resource-manager is configured to store into this database, whose data lives in the persistent docker volume bizone-mysql-data.

3. Start resource-manager; wait until GET /.system/status returns { "status": "OK" }.

4. Run the bizone-resources initialization job (blocking).

5. Import any configured resources namespaces (see above).

   Steps 4–5 are skipped entirely if the core resources were already imported, detected by querying GET /.global/resources?id=action/flow.start&expand=no; a 200 with a non-empty items array means the import already happened.

6. Start orchestrator, ui, and any enabled optional services in parallel (state-store / cloud-tools run only when *_enable=true).

   • The orchestrator receives the AWS env vars when forward_aws_env=true.

7. Wait for all of them to become ready:

   • ui — GET /actuator/health/readiness returns {"status":{"code":"UP"}}
   • all others — GET /.system/status returns { "status": "OK" }
   • each wait times out after timeout_sec seconds.

8. Start any custom services registered with bizone images add (last), then wait for the readiness each declares (see the images add section).

Each container is started with:

docker run -d \
  --name bizone-{type} -h bizone-{type} \
  --network bizone-local --network-alias bizone-{type} \
  -p {host_port}:{container_port} \
  [-e NAME=value ...] \
  {image}

stop — stop the platform

bizone stop

Reads containers.json, validates each id against docker ps, stops & removes the running containers, and updates the local file.

The database is intentionally left running so its data persists and the next bizone start reuses it. To remove the database, use bizone db destroy.

database — manage the MySQL database

bizone database destroy   # remove the DB container and its data volume

The bundled mysql container stores its data in the persistent docker volume bizone-mysql-data, so it survives bizone stop and container restarts.

destroy permanently removes both the bizone-mysql container and the bizone-mysql-data volume (all data is lost). It refuses to run while any other platform container (bizone-*) is still running — run bizone stop first.

Troubleshooting

• "Docker does not appear to be running" — start Docker Desktop / the Docker daemon.

• Startup timed out — increase timeout_sec, or check the container logs with docker logs bizone-{type}.

• Port already in use — change the relevant *_port config value.

• Stale containers blocking a re-run — bizone start force-removes existing bizone-* containers by name before starting; you can also run bizone stop.

• pull access denied from AWS ECR — when an image lives in an {account}.dkr.ecr.{region}.amazonaws.com registry and the pull is unauthorized, bizone start automatically authenticates by running aws ecr get-login-password --region {region} and piping it into docker login --username AWS --password-stdin {registry}, then retries. This requires the AWS CLI to be installed and configured with valid credentials for that account. If your default profile lacks access to that ECR, point the login at another profile:

  bizone config set aws_profile my-ecr-profile