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
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
string— Custom moniker for DID creation. Use commas to separate multiple values. - --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
string— Develop the blocklet as a component and mount it to the specified application DID. - --mount-point
string— Specify the mount point within the parent application. - --store-url
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
- [removed]
string(required) — The path to the script to execute.
Options
- --app-id
string— Execute the script within the context of the specified running application. - --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
-
string(required) — The debug string to set (e.g.,*,my-app:*).
Options
- --app-id
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
-
string(required) — The component to add (e.g.,component-name@1.0.0or a URL).
Options
- --profile
string(default:default) — The configuration profile to use. - --store
string— Specify the store from which to fetch the component. - --title
string— Custom title for the component. - --mount-point
string— The mount point for the component.
blocklet remove
Remove a component dependency from your blocklet.yml file.
Usage
blocklet remove <component>Arguments
-
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(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(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
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
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
-
string(required) — The directory containing the bundled blocklet.
Options
- --endpoint
string— The endpoint of the remote Blocklet Server dashboard (e.g.,http://127.0.0.1/admin). - --access-key
string— Access key for the remote Blocklet Server. - --access-secret
string— Access secret for the remote Blocklet Server. - --app-id
string— The application DID to which the component will be mounted. - --mount-point
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
string(default:default) — The configuration profile to use. - --access-token
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
-
string(required) — The URL of the Blocklet Store.
Options
- --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 metablocklet 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
string— The target to clean up. Available options:cache,backup. - --app-did
string— The DID of the blocklet to clean up.