bos

name	bos
description	CLI for everything-dev Module Federation projects. Use when creating new BOS projects, publishing bos.config.json to Near Social, syncing with remote configs (every.near/everything.dev), running development servers (bos dev), or building/deploying federated apps. Deploy → publish → sync workflow for shared configuration.

everything-dev CLI

CLI for everything-dev Module Federation projects with runtime-loaded configuration.

Quick Start

# Create new project (defaults to every.near/everything.dev template)
bos create project my-app

# Or with all arguments (no prompts)
bos create project my-app \
  --account myname.near \
  --testnet myname.testnet \
  --template bos://every.near/everything.dev

# Or sync an existing project with the root template
bos sync

# Start development (auto-detects missing packages → uses remote)
bos dev

Development Workflow

Auto-detection: The CLI automatically detects which packages exist locally and uses remote mode for missing ones. No need to explicitly specify --host=remote, --ui=remote, etc.

bos dev                      # Auto-detects: missing packages use remote
bos dev --host remote        # Explicit remote host (optional)
bos dev --ui remote          # Explicit remote UI (optional)  
bos dev --api remote         # Explicit remote API (optional)

Example output when packages are missing:

  ⚙ Auto-detecting packages...
    host not found locally → using remote
    api not found locally → using remote

Production mode:

bos start --no-interactive   # All remotes, production URLs

Deploy → Publish → Sync

The core workflow for sharing configuration:

# 1. Deploy apps to Zephyr (updates bos.config.json with production URLs)
bos deploy

# 2. Publish config to Near Social (on-chain registry)
bos publish

# 3. Others sync from your published config
bos sync --account your.near --gateway your-gateway.com

Default sync source: every.near/everything.dev

Key Commands

Command	Description
bos create project <name>	Scaffold new project (interactive or with args)
bos sync	Sync from every.near/everything.dev
bos dev	Development (auto-detects missing packages)
bos start --no-interactive	Production mode
bos build	Build existing packages (skips missing)
bos deploy	Deploy existing packages to Zephyr
bos publish	Publish config to Near Social
bos info	Show current configuration
bos status	Check remote health

Create Project Options

Create a new project with interactive prompts or skip prompts using arguments:

# Interactive (prompts for account, testnet, etc.)
bos create project my-app

# Skip all prompts with arguments
bos create project my-app \
  --account myname.near \
  --testnet myname.testnet \
  --template bos://every.near/everything.dev \
  --include-host \
  --include-gateway

Option	Description
-a, --account <account>	NEAR mainnet account (e.g., myname.near)
--testnet <account>	NEAR testnet account (optional)
-t, --template <url>	Template BOS URL (default: bos://every.near/everything.dev)
--include-host	Include host package locally (default: false, uses remote)
--include-gateway	Include gateway package locally (default: false, uses remote)

Auto-Detection Behavior

Commands automatically detect which packages exist locally:

Command	Missing Package Behavior
bos dev	Uses remote mode
bos build	Skips package
bos deploy	Skips package

Process Management

Command	Description
bos ps	List all tracked BOS processes
bos kill	Kill all tracked processes (graceful SIGTERM → SIGKILL)
bos kill --force	Force kill all processes immediately (SIGKILL)

Process tracking uses .bos/pids.json to track spawned processes for cleanup.

Docker Commands

Command	Description
bos docker build	Build production Docker image
bos docker build --target development	Build development/agent-ready image
bos docker build --no-cache	Build without cache
bos docker run	Run container in production mode
bos docker run --detach	Run container in background
bos docker run --target development --mode serve	Run agent-ready container (RPC exposed)
bos docker stop <containerId>	Stop specific container
bos docker stop --all	Stop all BOS containers

Docker modes:

• start (default): Production mode, fetches config from Near Social
• serve: Exposes CLI as RPC API (agent-ready)
• dev: Full development mode

For full command reference, see commands.md.

Configuration

All runtime configuration lives in bos.config.json. See types.md for the schema.

Key fields:

• account - NEAR account (mainnet)
• testnet - NEAR account (testnet)
• template - Default template for scaffolding
• app.host, app.ui, app.api - Module configuration

Workflow Patterns

For detailed workflow guides, see workflows.md:

• Creating a new project
• Syncing with upstream
• Publishing updates
• Working with secrets
• Gateway deployment

File References

Key files for understanding the system:

• bos.config.json - Runtime configuration
• demo/cli/src/types.ts - BosConfig schema
• demo/cli/src/cli.ts - CLI implementation
• demo/cli/src/plugin.ts - Command handlers