bos - SKILL.md Agent Skill

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