cli-reference

name	cli-reference
description	Quick reference for all bos CLI commands — flags, options, environment settings, and links to detailed guidance in related skills. Use when any bos command comes up or the user needs a CLI overview.
metadata	{"sources":"packages/everything-dev/src/contract.ts,packages/everything-dev/src/contract.meta.ts,packages/everything-dev/src/cli.ts,packages/everything-dev/src/cli/catalog.ts"}

CLI Command Reference

17 bos commands organised by workflow category.

Development

bos dev

Start a development session. Runs host, API, auth, and UI processes with hot reload.

Flags: --host <local|remote> --ui <local|remote> --api <local|remote> --auth <local|remote> --remote-plugins <ids> --proxy --ssr --port <n>

bos dev                   # full local (all services)
bos dev --api remote      # UI-only mode, use remote API
bos dev --ui remote       # API-only mode, use remote UI
bos dev --proxy           # local host proxies to remote API/UI
bos dev --remote-plugins auth,registry  # force specific plugins remote

→ dev-workflow skill for port assignments, service-descriptor architecture, hot reload, and debugging.

bos start

Start the production host. Loads config from bos.config.json, wires MF remotes, serves SSR.

Flags: --env <production|staging> --port <n> --account <id> --domain <domain> --no-interactive

bos start                          # production, auto-detects env
bos start --env staging            # staging mode
bos start --account myapp.near     # tenant override

→ dev-workflow skill for production topology and super-app for tenant overrides.

bos build

Build all workspace packages (or a subset) for production.

Flags: --packages <list> --force --deploy

bos build                    # build all workspaces
bos build --packages ui,api  # build specific packages
bos build --force            # rebuild even if up-to-date
bos build --deploy           # build + deploy to Zephyr

→ publish-sync skill for full deploy+publish workflow.

bos config

Print the loaded configuration (plain or fully resolved).

Flags: --full

bos config        # print bos.config.json with env overrides applied
bos config --full # print fully resolved config (extends + deep merge)

→ extends-config skill for deep merge semantics and resolved config lifecycle.

Lifecycle

bos init

Scaffold a new project from a deployed app or template. Interactive by default.

Flags: --extends <ref> --directory <dir> --account <id> --domain <d> --source <dir> --plugins <list> --overrides <sections> --no-interactive --no-install

bos init                                       # interactive wizard
bos init mysite.everything.dev                 # quick scaffold from current config
bos init --extends bos://account/gateway       # from a specific parent
bos init --overrides ui,api,host,plugins       # customise local sections
bos init --source ./my-app --no-interactive    # from local source, skip prompts

→ init-upgrade skill for template download, file selection, snapshots, and conflict wiring.

bos sync

Sync template files from the parent project. Compares snapshot-versioned files to detect conflicts.

Flags: --dry-run --no-install

bos sync
bos sync --dry-run    # preview without writing

→ init-upgrade skill for snapshot-based conflict detection and framework-owned sections.

bos upgrade

Upgrade framework packages then sync template files. Interactive; prompts for package selection.

Flags: --dry-run --no-install --no-sync

bos upgrade
bos upgrade --dry-run       # preview version bumps
bos upgrade --no-sync       # only upgrade packages, skip template sync

→ init-upgrade skill for catalog strategy, legacy import rewrites, and upgrade+publish flow.

bos status

Show project health: package versions, parent reachability, last sync, env file status, and update availability.

bos status

Output includes installed vs latest versions for each workspace package, whether the parent extends reference is reachable, whether .env exists, and when the last sync ran. No flags.

Publishing

bos publish

Publish bos.config.json to the FastKV on-chain registry. Optionally build and deploy workspaces first.

Flags: --deploy --dry-run --network <mainnet|testnet> --private-key <key> --env <production|staging> --packages <list>

bos publish                    # publish current config snapshot
bos publish --deploy           # build all + deploy + publish
bos publish --dry-run          # preview what would be published
bos publish --network testnet  # publish to testnet registry

→ publish-sync skill for config sections, SRI integrity, rollback, and FastKV troubleshooting.

bos deploy

Publish config and trigger a Railway redeploy. Builds and deploys by default.

Flags: --env <production|staging> --no-build --dry-run --network <mainnet|testnet> --private-key <key> --service <name> --packages <list>

bos deploy                        # build + publish + trigger deploy
bos deploy --no-build             # publish only, skip workspace build
bos deploy --service my-railway   # override Railway service name

→ publish-sync skill and super-app for tenant-aware deploy considerations.

bos key publish

Generate a publish access key (NEAR function-call key) scoped to the FastKV registry contract.

Flags: --allowance <amount> (default: 0.25NEAR)

bos key publish                    # generate key with default allowance
bos key publish --allowance 1NEAR  # custom allowance

Outputs the public key, private key, and registry contract address. The generated key can only call the set and get methods on the BOS registry contract — it cannot transfer funds or call other contracts.

Plugins

bos plugin add

Add a plugin attachment to bos.config.json from a local path, BOS reference, or remote URL.

Flags: <source> (positional) --as <alias> --production <url>

bos plugin add local:plugins/my-plugin                         # local plugin
bos plugin add bos://account/gateway                           # from BOS registry
bos plugin add https://cdn.example.com/remoteEntry.js           # remote URL
bos plugin add local:plugins/my-plugin --as my-alias            # with alias
bos plugin add local:plugins/my-plugin --production <prod-url>  # separate prod URL

→ plugin-development skill for plugin anatomy, contract/service/index pattern, and registration.

bos plugin remove

Remove a plugin attachment from bos.config.json.

Flags: <key> (positional)

bos plugin remove my-plugin

bos plugin list

List all configured plugins with their sources (local vs remote), versions, and integrity hashes.

bos plugin list

Outputs each plugin's key, development source, production URL, local path, version, and SRI integrity hash.

bos plugin publish

Build and publish a single plugin to Zephyr CDN, then update bos.config.json with the production URL and SRI integrity hash.

Flags: <key> (positional)

bos plugin publish my-plugin

→ plugin-development skill for build config (rspack.config.js), CLI lifecycle, and deploy workflow.

Types & DB

bos types gen

Generate and fetch type definitions from configured API and plugin contracts. Runs automatically on bun install, bos dev, bos build, bos plugin add, and bos plugin remove.

Flags: --env <development|production> --dry-run

bos types gen                     # development mode (local + remote sources)
bos types gen --env production    # production mode (remote sources only)
bos types gen --dry-run           # preview without writing files

Generated files: api-types.gen.ts, auth-types.gen.ts (ui, api, host), plugins-types.gen.ts. Uses local: sources in dev and production URLs in production mode.

bos db studio

Open Drizzle Studio for inspecting a plugin's database.

Flags: <plugin> (positional, default: api)

bos db studio             # open Drizzle Studio for the API database
bos db studio auth        # open for the auth plugin
bos db studio my-plugin   # open for a custom plugin

Requires the DATABASE_URL secret to be set on the target plugin. Uses the plugin's drizzle.config.ts for schema discovery.