BLOX CLI

Prerequisites

• Install yarn

Install

It can have many way to be installed, mainly as global npm package

  npm install -g patch-package @naseej/blox

• make sure npm is already in you $Path to be able to use blox globally

Usage

  blox --help

BLOX CLI

Commands:
  blox init    Init new app                                         [alias: i]
  blox add     Add block to app                                     [alias: a]
  blox remove  Remove block from app                                [alias: rm]
  blox update  Update app/block                                     [alias: u]
  blox contribute Contribute changes to template/base/block repos   [alias: cb]
  blox conf    Set blox global config                               [alias: c]
  blox upgrade Upgrade blox cli to latest version
  blox migrate Migrate blox schema
  blox detach  Detach to base
  blox skills Install and manage BLOX CLI skills (wraps npx skills)

Options:
  -V, --version  Show version number                                       [boolean]
  -h, --help     Show help                                                 [boolean]
  -d, --debug    Works in debug mode                                       [boolean]
  -m, --minimal  Works in minimal mode                                     [boolean]

• Use minimal mode if spinners are getting in the way of needed input for example.

Available commands

• init
• add
• remove
• update
• contribute
• conf
• upgrade
• migrate
• skills

Ignore policy

Ignore rules tell BLOX which files or paths to skip.

Add project-level ignore rules in your root .blox file:

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

How it works in a simple way:

Quick difference:

• definition.ignore: comes from the remote template/block (maintainer controls it).

• project.ignore: local to your app (you control it).

• blox update combines ignore patterns from multiple places:

  • remote template ignore (definition.ignore)
  • local project ignore (project.ignore in your local .blox)
  • local .gitignore
  • command option --ignore (when provided)

• blox contribute also respects local project.ignore, so matching files are not included in contributed commits.

• 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.
They can exist in:

• the root template (.blox at app root)
• each block (blocks/<name>/.blox)

hooks names: init, add, update, remove.

When they run

| Hook | Template (root .blox) | Block (blocks/.../.blox) | | -------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | init | Runs afterblox 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, but only if at least one new block was added (including dependencies). | Runs when the block is added , right after the init hook for that new block, still before dependencies. | | update | After blox update when the root template or a base or a block remote actually advanced (new commit applied). | Only when that block’s remote actually advanced (new commit). Skipped if already up to date. | | remove | After blox remove actually removed a block in that run. | Runs before the block is deleted, while its files still exist. |

init

  blox init --help

blox init

Init new app

Options:
  -n, --name      App name
  -t, --template  Template to use
  --branch, branch name to use

add

  blox add --help

blox add [blocks]

Add block to app

Params:
  blocks  Block names separated by space (optional; if omitted, prompts with multiselect from available blocks)

Options:
  --branch, branch name to use (applies to all selected blocks)
  --dest, destination dir (applies to all selected blocks)

• You can add multiple blocks in one command, for example: blox add components applet-template.
• Blocks are processed sequentially in the order provided.

remove

  blox remove --help

blox remove [blocks]

Remove block from app

Params:
  blocks  Blocks to remove separated by space — registry keys or installed folder names under blocks/ (optional; prompts with multiselect from installed blocks)

Options:
  -f, --force  Remove even if other blocks declare a dependency on them (global for all selected blocks; skips dependency guard and post-remove version compatibility check)

• Only directories under blocks/ that contain a valid .blox file are treated as removable blocks; other folders are ignored for selection and removal.
• You can remove multiple blocks in one command, for example: blox remove components applet-template.
• Blocks are processed sequentially in the order provided.

update

  blox update --help

blox update

Update app/block

Options:
  -s, --scope          Scope of update [choices: "app", "bases", "block", "all"] [default: "all"]
  -b, --block          Block to update, valid only with scope block

• Note: you may need to resolve merge conflicts if found

contribute

  blox contribute --help

blox contribute

Contribute changes back to template/base/block repositories

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: template | base | block
  --name <name>           Target name (with --type)

conf

  blox sync --help

blox conf

Set blox global config

Options:
  -r, --registries Remote registries urls

upgrade

  blox upgrade

blox upgrade

Upgrade blox cli to latest version

migrate

  blox migrate --help

blox migrate

Migrate blox schema

Installing Blox CLI Skills

Use blox skills to run the Skills CLI against the BLOX CLI skills repository. No repo URL needed, BLOX clones the repo, executes npx skills with your arguments, then cleans up. Anything you pass after skills works the same as with npx skills.

CLI version compatibility

Skills declare a cliCompatibility range in skill.json (npm semver range). For blox skills add and blox skills update, BLOX checks that your installed CLI version satisfies that range before running npx skills. If it does not, you’ll see a warning with the required range and your current version, then a Yes / No prompt: continue anyway, or exit and run blox upgrade first.

Common commands

Add skills :

blox skills add

Install to Cursor only, skipping prompts where supported:

blox skills add -a cursor -y

Install to several agents at once:

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

List skills already installed (project and global):

blox skills list

Compatibility

These skills are not tied to a specific editor or product. They work across tools that support skill-style instructions. Metadata marks agents as generic for broad use.