exec
The blocklet exec command executes a specified Node.js script within the runtime context of a running Blocklet or one of its components. This is particularly useful for one-off tasks, database migrations, or administrative scripts that require access to a Blocklet's secure environment variables.
Before using this command, ensure that your Blocklet Server is running. You can start it using the blocklet server start command.
Execution Flow#
When you run blocklet exec, the CLI performs a series of steps to securely execute your script in the correct environment.
Usage#
blocklet exec <script-path> [options]Arguments#
Argument | Description |
|---|---|
| Required. The path to the Node.js script to execute, relative to your current directory. |
Options#
Option | Description | Required | Default |
|---|---|---|---|
| The DID of the target Blocklet where the script will run. Can also be supplied by the | Yes | - |
| The maximum execution time for the script in seconds. If the script exceeds this duration, it will be terminated. | No |
|
Examples#
Execute a Script in a Blocklet#
Suppose you have a script named scripts/check-env.js designed to read an environment variable from your Blocklet.
Script (scripts/check-env.js)
// This script reads an environment variable provided by the Blocklet.
async function checkVariable() {
console.log('Attempting to read MY_CUSTOM_VAR...');
const myVar = process.env.MY_CUSTOM_VAR;
if (myVar) {
console.log(`Success! MY_CUSTOM_VAR = ${myVar}`);
} else {
console.error('Error: MY_CUSTOM_VAR is not defined in the Blocklet environment.');
}
}
checkVariable();To run this script inside your running Blocklet, use the following command, replacing the --app-id with your Blocklet's DID:
blocklet exec scripts/check-env.js --app-id z8iZt...WzNezExpected Output
info Try to run script for blocklet(z8iZt...WzNez) (timeout: 1800000ms)
Attempting to read MY_CUSTOM_VAR...
Success! MY_CUSTOM_VAR = itsASecret
success Done!Execute a Script in a Component's Context#
If you run blocklet exec from a directory that is a Blocklet Component (identified by a blocklet.yml file), the script will automatically execute within that component's specific environment. The --app-id should point to the parent Blocklet that contains the component.
Consider a parent Blocklet that has a component with the following blocklet.yml:
Component blocklet.yml
name: my-component
did: z2qa...
main: blocklet.js
# ... other component settingsWhen you run the command from this component's directory, the script gains access to the environment variables defined for my-component.
# Ensure you are in the my-component directory
blocklet exec scripts/component-task.js --app-id z8iZt...WzNezThis command executes scripts/component-task.js within the environment of my-component, which is a child of the Blocklet specified by z8iZt...WzNez.
For interactive development workflows, you may also find the blocklet dev command useful. To add or remove components, see blocklet add and blocklet remove.