blocklet

The blocklet command is the primary interface for managing the entire lifecycle of a Blocklet project. It provides a comprehensive suite of subcommands for initializing, developing, bundling, deploying, and managing blocklets and their components.

Global Options#

-y, --yes
boolean
default:false
Automatically answer yes to any interactive prompts. This is useful for scripting and automation.


Project Setup#

Commands to bootstrap and initialize new Blocklet projects.

blocklet create#

Bootstrap a new Blocklet project from various starter templates.

Usage

blocklet create [name] [options]

Arguments

[name]
string
The name for the new blocklet project. If omitted, you will be prompted to enter one.

Options

--did <did>
string
Specify a pre-existing DID for the new blocklet.
--did-only
boolean
Only create a blocklet DID without creating a project.

blocklet init#

Initialize an empty Blocklet project in the current directory. This command creates the blocklet.yml file and essential project structure.

Usage

blocklet init [options]

Options

--did [did]
string
Specify a pre-existing DID for the blocklet.
-f, --force
boolean
default:false
Initialize the project without any interactive prompts.
--monikers <monikers>
string
Custom moniker for DID creation. Use commas to separate multiple values.
--connectUrl <connectUrl>
string
A connect URL to assist in DID generation.


Local Development#

Commands for running, testing, and debugging your blocklet in a local environment.

blocklet dev#

Run the blocklet in development mode from the current directory, connecting it to the local Blocklet Server.

Usage

blocklet dev [subcommand] [options]

Options

--open
boolean
default:false
Open the browser after the blocklet has started.
--app-id <did>
string
Develop the blocklet as a component and mount it to the specified application DID.
--mount-point <mountPoint>
string
Specify the mount point within the parent application.
--store-url <storeUrl>
string
Default store URL to use when a component's source store is not declared.
--start-all-components
boolean
default:false
Automatically start all components within the blocklet.

Subcommands

Command

Description

install

Install the development mode blocklet.

start

Start the development blocklet after it has been installed. Supports --e2e option.

remove

Remove the development mode blocklet.

studio

Start the Blocklet Studio.

reset

Reset the blocklet's data. Alias: clear.

faucet

Fund your app with test tokens from a faucet. Supports --host and --token options.

blocklet test#

Set up and manage a test environment for your blocklet.

Usage

blocklet test [subcommand] [options]

Subcommands

Command

Description

init

Initialize a new blocklet for testing. Supports --app-sk, --owner-sk, --app-name options.

start

Start the test blocklet. Supports --app-sk option.

remove

Completely delete the test blocklet. Supports --app-sk option.

reset

Reset the state of the test blocklet. Supports --app-sk option.

blocklet exec#

Execute a script within the running context of a blocklet.

Usage

blocklet exec <script> [options]

Arguments

<script>
string
required
The path to the script to execute.

Options

--app-id <did>
string
Execute the script within the context of the specified running application.
--timeout <timeout>
number
Maximum time in seconds for the script to run.

blocklet debug#

Set the DEBUG environment variable for a blocklet.

Usage

blocklet debug <value> [options]

Arguments

<value>
string
required
The debug string to set (e.g., `*`, `my-app:*`).

Options

--app-id <did>
string
Set the debug configuration for the specified application.


Component Management#

Commands for managing component dependencies within your blocklet.

blocklet add#

Add a component as a dependency to your blocklet.yml file.

Usage

blocklet add <component> [options]

Arguments

<component>
string
required
The component to add (e.g., `component-name@1.0.0` or a URL).

Options

--profile <profile>
string
default:default
The configuration profile to use.
--store <store>
string
Specify the store from which to fetch the component.
--title <title>
string
Custom title for the component.
--mount-point <mountPoint>
string
The mount point for the component.

blocklet remove#

Remove a component dependency from your blocklet.yml file.

Usage

blocklet remove <component>

Arguments

<component>
string
required
The name of the component to remove.

blocklet component#

Execute commands from the Component Studio CLI.

Usage

blocklet component [command...]

This command acts as a proxy, passing all subsequent arguments to the @blocklet/component-studio-cli.


Packaging & Versioning#

Commands to prepare your blocklet for distribution.

blocklet bundle#

Package your blocklet and its assets into a deployable bundle.

Usage

blocklet bundle [options]

Options

--zip
boolean
default:true
Bundle using zip mode (default).
--simple
boolean
default:false
Bundle using simple mode.
--compact
boolean
default:false
Bundle using compact mode, including all dependencies.
--dependencies-depth <number>
number
default:9
The depth of dependencies to include in the bundle.
--source-map
boolean
default:false
Create a source map (compact mode only).
--nosources-source-map <boolean>
boolean
default:false
Create a source map without including sources content (compact mode only).
--minify / --no-minify
boolean
default:true
Enable or disable minification in compact mode.
--external <items>
string
Comma-separated list of external dependencies to exclude from the bundle.
--create-release
boolean
default:false
Create a release tarball and metadata for the bundled blocklet.
--create-archive
boolean
default:false
Create an archive *.zip file for the bundled blocklet.
--monorepo
boolean
default:false
Bundle a blocklet that is part of a monorepo.
--changelog / --no-changelog
boolean
default:true
Include or exclude CHANGELOG.md in the bundle.
--store-url <storeUrl>
string
Default store URL to use when a component's source store is not declared.

blocklet version#

Bump the blocklet's version in blocklet.yml.

Usage

blocklet version [newVersion] [options]

Arguments

[newVersion]
string
default:patch
The new version or the type of increment (e.g., `1.2.3`, `major`, `minor`, `patch`).

Options

--git-commit
boolean
Create a git commit after bumping the version.
-f, --force
boolean
Force the version bump, even if it's a downgrade.


Distribution#

Commands for deploying your blocklet to a server or uploading it to a store.

blocklet deploy#

Deploy a blocklet from a local directory to a Blocklet Server instance.

Usage

blocklet deploy <folder> [options]

Arguments

<folder>
string
required
The directory containing the bundled blocklet.

Options

--endpoint <host>
string
The endpoint of the remote Blocklet Server dashboard (e.g., `http://127.0.0.1/admin`).
--access-key <key>
string
Access key for the remote Blocklet Server.
--access-secret <secret>
string
Access secret for the remote Blocklet Server.
--app-id <did>
string
The application DID to which the component will be mounted.
--mount-point <mountPoint>
string
The mount point within the application.
--incremental
boolean
default:false
Deploy only the files that have changed since the previous version.

blocklet upload#

Upload a bundled blocklet to a Blocklet Store.

Usage

blocklet upload [metafile] [options]

Arguments

[metafile]
string
Path to the blocklet's release metadata file (e.g., `.blocklet/release/blocklet.json`).

Options

--profile <profile>
string
default:default
The configuration profile to use.
--access-token <accessToken>
string
Access token for the Blocklet Store.

blocklet connect#

Connect and authenticate the CLI with a Blocklet Store.

Usage

blocklet connect <store-url> [options]

Arguments

<store-url>
string
required
The URL of the Blocklet Store.

Options

--profile <profile>
string
default:default
The configuration profile to use for storing the connection details.


Utilities#

Helper commands for managing configurations and metadata.

blocklet config#

Manage the local configuration for the Blocklet CLI.

Usage

blocklet config [subcommand] [key] [value]

Subcommands

Command

Description

set [key] [value]

Set a configuration value.

get [key]

Get a configuration value.

delete [key]

Delete a configuration value.

list

List all configuration values. Alias: ls.

blocklet meta#

Parse and print the blocklet.yml metadata from the current directory.

Usage

blocklet meta

blocklet document#

Manage the DID document for a blocklet.

Usage

blocklet document update <app-id>

Subcommands

Command

Description

update <app-id>

Update the DID document for the specified blocklet.

blocklet cleanup#

Perform cleanup tasks for a specific blocklet.

Usage

blocklet cleanup [options]

Options

--target <target>
string
The target to clean up. Available options: `cache`, `backup`.
--app-did <did>
string
The DID of the blocklet to clean up.
blocklet server
Environment Variables