BLOX CLI

BLOX CLI helps you bootstrap, manage, update, and contribute BLOX-based apps and blocks.

Content

• BLOX CLI
  • Content
  • Installation
  • Quick Start
  • Commands
    • init
    • add
    • remove
    • update
    • contribute
    • conf
    • upgrade
    • migrate
    • skills
  • Features
    • Ignore Policy
    • Lifecycle Hooks
    • Skills
      • Installing Skills
      • CLI Compatibility
      • Common Commands
      • Compatibility
    • Create new template
      • 1 - Initialize from an existing template
      • 2 - Update .blox configuration
      • 3 - Publish and register the template

Installation

Install globally with npm:

npm install -g patch-package @naseej/blox

Notes:

• Ensure npm is available in your PATH.
• Use minimal mode (-m, --minimal) if spinners interfere with interactive input.

Quick Start

Start with the core commands:

blox --help
blox init
blox add
blox update

Commands

Other available command:

• blox detach: detach to base

init

Initialize a new app.

Usage:

blox init

Important options:

• -n, --name: app name
• -t, --template: template to use
• --branch: branch name to use

add

Add one or more blocks to an app.

Usage:

blox add [blocks]

Example:

blox add components applet-template

Important options:

• --branch: branch name (applies to all selected blocks)
• --dest: destination directory (applies to all selected blocks)

Important notes:

• If blocks are omitted, BLOX prompts with a multiselect from available blocks.
• Blocks are processed sequentially in the order provided.

remove

Remove one or more installed blocks.

Usage:

blox remove [blocks]

Example:

blox remove components applet-template

Important options:

• -f, --force: remove even when other blocks depend on them

Important notes:

• If blocks are omitted, BLOX prompts with a multiselect from installed blocks.
• You can pass registry keys or installed folder names under blocks/.
• Only directories under blocks/ containing a valid .blox file are treated as removable blocks.
• Blocks are processed sequentially in the order provided.

update

Update the app, bases, or specific blocks.

Usage:

blox update

Important options:

• -s, --scope: app, bases, block, or all (default: all)
• -b, --block: block to update (valid only when --scope block)

Important notes:

• You may need to resolve merge conflicts.
• If a template, base, or block is missing from the registry, BLOX prompts you to continue or stop.

contribute

Contribute app changes back to template/base/block repositories.

Usage:

blox contribute

Important options:

• --existing: add changes to an existing contribution branch
• --title <title>: contribution title
• --description <text>: contribution description
• --commits <commits>: comma-separated commit hashes from the app repo
• --force: bypass safety pre-flight checks
• --type <type>: target type (template, base, or block)
• --name <name>: target name (used with --type)

conf

Set global BLOX configuration.

Usage:

blox conf

Important options:

• -r, --registries: remote registry URLs

upgrade

Upgrade BLOX CLI to the latest version.

Usage:

blox upgrade

migrate

Migrate BLOX schema.

Usage:

blox migrate

skills

Install and manage BLOX CLI skills (wraps npx skills).

Usage:

blox skills <command> [options]

Important notes:

• BLOX clones the BLOX CLI skills repository, runs npx skills with your arguments, then cleans up.
• No repository URL is required.

Features

Ignore Policy

Ignore rules tell BLOX which files or paths to skip.

Template-level ignore:

• Defined in definition.ignore.
• Comes from template/block maintainers.

App-level ignore:

• Defined in project.ignore.
• Local to your app and controlled by you.

Example root .blox configuration:

{
    "project": {
        "ignore": ["applet-core", "dist/**", "*.generated.ts"]
    }
}

How ignore sources are combined:

• blox update combines patterns from:
  • remote template ignore (definition.ignore)
  • local project ignore (project.ignore in local .blox)
  • local .gitignore
  • command option --ignore (when provided)
• blox contribute also respects local project.ignore.
• Local project.ignore is project-owned and is not replaced by remote template ignore during update.

Lifecycle Hooks

Lifecycle hooks are optional shell commands defined in .blox files.

Where hooks can be defined:

• Root template: .blox at app root
• Each block: blocks/<name>/.blox

Supported hooks:

• init
• add
• update
• remove

When hooks run:

| Hook | Template (root .blox) | Block (blocks/.../.blox) | | -------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- | | init | Runs after blox init finishes creating the app. | Runs after a new block is cloned and initialized, before its dependencies are added. | | add | Runs once per blox add command, only if at least one new block was added (including dependencies). | Runs when the block is added, right after that new block's init hook, still before dependencies. | | update | Runs after blox update when the root template, a base, or a block remote actually advanced (new commit applied). | Runs only when that block's remote actually advanced (new commit). Skipped if already up to date. | | remove | Runs after blox remove actually removed a block in that run. | Runs before the block is deleted, while its files still exist. |

Skills

Installing Skills

Use blox skills to run the Skills CLI against the BLOX CLI skills repository.

Behavior:

• BLOX executes npx skills with all arguments passed after skills.
• BLOX handles cloning and cleanup automatically.

CLI Compatibility

Skills declare a cliCompatibility range in skill.json (npm semver).

For blox skills add and blox skills update:

• BLOX checks whether your installed CLI version satisfies the required range.
• If not, BLOX shows the required range and your current version.
• You can choose to continue or exit and run blox upgrade first.

Common Commands

blox skills add
blox skills add -a cursor -y
blox skills add -a cursor -a claude-code -y
blox skills list

Compatibility

Skills are not tied to a specific editor or product. They work across tools that support skill-style instructions, and metadata marks agents as generic for broad use.

Create new template

Create a new template by starting from an existing one, updating its metadata, then publishing it.

1 - Initialize from an existing template

Create a new project using the template you want to build on.

Example:

blox init -n my-template -t existing-template

2 - Update .blox configuration

Edit your project's .blox file to describe the new template.

• Set definition.name to your new template name.
• Keep the original template in the bases list so you can continue receiving updates from it.

3 - Publish and register the template

• Push the template project to a remote repository.
• Add that repository to a BLOX registry (Or any custom registry) so BLOX CLI can discover and use your template.