CLI Reference
All commands, subcommands, flags, and environment variables
14
commands
Click
framework
merobox
entry point
Python
language
Command Overview
merobox provides top-level commands for node management, workflow orchestration, and environment control.
Node Management
Commands for starting, stopping, listing, monitoring, and destroying Calimero nodes.
merobox run
Start Calimero nodes in Docker containers or as native processes.
merobox run [OPTIONS]
Options:
--count INTEGER Number of nodes to start (default: 1)
--prefix TEXT Node name prefix (default: "calimero-node")
--restart Restart existing nodes
--image TEXT Custom Docker image to use
--force-pull Force pull image even if it exists locally
--no-docker Run as native processes instead of Docker
--binary-path PATH Path to merod binary (required with --no-docker)
Auth options:
--auth-service Enable Traefik + auth stack (Docker mode only)
--auth-image TEXT Custom auth service image
--auth-mode [embedded|proxy] Auth mode for merod (binary mode only)
--auth-use-cached Use cached auth frontend (skip fresh fetch)
--webui-use-cached Use cached WebUI frontend (skip fresh fetch)
Logging:
--log-level TEXT RUST_LOG level (default: debug). Supports patterns:
"info,module::path=debug"
--rust-backtrace TEXT RUST_BACKTRACE level (default: 0)
Options:
--count INTEGER Number of nodes to start (default: 1)
--prefix TEXT Node name prefix (default: "calimero-node")
--restart Restart existing nodes
--image TEXT Custom Docker image to use
--force-pull Force pull image even if it exists locally
--no-docker Run as native processes instead of Docker
--binary-path PATH Path to merod binary (required with --no-docker)
Auth options:
--auth-service Enable Traefik + auth stack (Docker mode only)
--auth-image TEXT Custom auth service image
--auth-mode [embedded|proxy] Auth mode for merod (binary mode only)
--auth-use-cached Use cached auth frontend (skip fresh fetch)
--webui-use-cached Use cached WebUI frontend (skip fresh fetch)
Logging:
--log-level TEXT RUST_LOG level (default: debug). Supports patterns:
"info,module::path=debug"
--rust-backtrace TEXT RUST_BACKTRACE level (default: 0)
Examples
# Start 2 nodes with default settings
merobox run --count 2
# Start with auth service
merobox run --auth-service --count 2
# Binary mode with embedded auth
merobox run --no-docker --binary-path /usr/local/bin/merod --auth-mode embedded
# Force pull latest image
merobox run --image ghcr.io/calimero-network/merod:edge --force-pull
merobox run --count 2
# Start with auth service
merobox run --auth-service --count 2
# Binary mode with embedded auth
merobox run --no-docker --binary-path /usr/local/bin/merod --auth-mode embedded
# Force pull latest image
merobox run --image ghcr.io/calimero-network/merod:edge --force-pull
merobox stop
Stop running Calimero nodes and optional auth service stack.
merobox stop [OPTIONS]
Options:
--all Stop all running nodes and auth service stack
--auth-service Stop auth service stack only (Traefik + Auth)
--prefix TEXT Stop nodes with specific prefix
Options:
--all Stop all running nodes and auth service stack
--auth-service Stop auth service stack only (Traefik + Auth)
--prefix TEXT Stop nodes with specific prefix
Examples
merobox stop --all
merobox stop --auth-service
merobox stop --prefix test-node
merobox stop --auth-service
merobox stop --prefix test-node
merobox list
List all running Calimero nodes managed by merobox.
merobox list [OPTIONS]
Options:
--help Show help message
Options:
--help Show help message
merobox health
Check health status of all running nodes.
merobox health [OPTIONS]
Options:
--help Show help message
Options:
--help Show help message
merobox logs
View or follow log output from a running node.
merobox logs [OPTIONS] NODE_NAME
Arguments:
NODE_NAME Node to show logs for required
Options:
--follow, -f Follow log output (like tail -f)
Arguments:
NODE_NAME Node to show logs for required
Options:
--follow, -f Follow log output (like tail -f)
Examples
merobox logs calimero-node-1
merobox logs calimero-node-1 --follow
merobox logs calimero-node-1 --follow
merobox nuke
Remove all merobox-managed resources: containers, volumes, binary processes, PID files, and temp data.
merobox nuke [OPTIONS]
Options:
--dry-run Show what would be deleted without deleting
--force, -f Force deletion without confirmation prompt
--verbose, -v Show verbose output
--prefix TEXT Filter nodes by prefix (e.g. "test-node-")
Options:
--dry-run Show what would be deleted without deleting
--force, -f Force deletion without confirmation prompt
--verbose, -v Show verbose output
--prefix TEXT Filter nodes by prefix (e.g. "test-node-")
Examples
merobox nuke --force
merobox nuke --dry-run --verbose
merobox nuke --prefix test-node
merobox nuke --dry-run --verbose
merobox nuke --prefix test-node
Workflow Orchestration
The bootstrap command executes, validates, and scaffolds workflows.
merobox bootstrap
Execute workflows, validate configurations, and create sample files.
merobox bootstrap <SUBCOMMAND> [OPTIONS]
Subcommands:
run <config_file> Execute a workflow
validate <config_file> Validate workflow configuration
create-sample Create a sample workflow file
Subcommands:
run <config_file> Execute a workflow
validate <config_file> Validate workflow configuration
create-sample Create a sample workflow file
bootstrap run
merobox bootstrap run <config_file> [OPTIONS]
Auth options:
--auth-service Enable Traefik + auth stack (Docker mode)
--auth-image TEXT Custom auth service Docker image
--auth-mode [embedded|proxy] Auth mode for merod (binary mode)
--auth-username TEXT Username for embedded auth (required with embedded)
--auth-password TEXT Password for embedded auth (required with embedded)
--auth-use-cached Use cached auth frontend
--webui-use-cached Use cached WebUI frontend
NEAR options:
--enable-relayer Use relayer/testnet instead of local sandbox
--contracts-dir PATH Directory with Calimero NEAR WASM contracts
Remote nodes:
--remote-node NAME=URL Register remote node (repeatable)
--remote-auth NAME=AUTH Set auth: name=user:pass or name=apikey:KEY
--api-key KEY Default API key for nodes without explicit auth
Logging:
--log-level TEXT RUST_LOG level for Calimero nodes (default: debug)
--rust-backtrace TEXT RUST_BACKTRACE level (default: 0)
--verbose, -v Enable verbose output
Auth options:
--auth-service Enable Traefik + auth stack (Docker mode)
--auth-image TEXT Custom auth service Docker image
--auth-mode [embedded|proxy] Auth mode for merod (binary mode)
--auth-username TEXT Username for embedded auth (required with embedded)
--auth-password TEXT Password for embedded auth (required with embedded)
--auth-use-cached Use cached auth frontend
--webui-use-cached Use cached WebUI frontend
NEAR options:
--enable-relayer Use relayer/testnet instead of local sandbox
--contracts-dir PATH Directory with Calimero NEAR WASM contracts
Remote nodes:
--remote-node NAME=URL Register remote node (repeatable)
--remote-auth NAME=AUTH Set auth: name=user:pass or name=apikey:KEY
--api-key KEY Default API key for nodes without explicit auth
Logging:
--log-level TEXT RUST_LOG level for Calimero nodes (default: debug)
--rust-backtrace TEXT RUST_BACKTRACE level (default: 0)
--verbose, -v Enable verbose output
Examples
# Basic workflow execution
merobox bootstrap run workflow.yml
# With auth service
merobox bootstrap run workflow.yml --auth-service
# Embedded auth (binary mode)
merobox bootstrap run workflow.yml --auth-mode embedded --auth-username admin --auth-password secret
# Use relayer instead of local sandbox
merobox bootstrap run workflow.yml --enable-relayer
# With remote nodes
merobox bootstrap run workflow.yml \
--remote-node prod=https://prod.example.com \
--remote-auth prod=admin:secret123
# Multiple remote nodes with API key
merobox bootstrap run workflow.yml \
--remote-node prod=https://prod.example.com \
--remote-node staging=https://staging.example.com \
--api-key sk-default-key
merobox bootstrap run workflow.yml
# With auth service
merobox bootstrap run workflow.yml --auth-service
# Embedded auth (binary mode)
merobox bootstrap run workflow.yml --auth-mode embedded --auth-username admin --auth-password secret
# Use relayer instead of local sandbox
merobox bootstrap run workflow.yml --enable-relayer
# With remote nodes
merobox bootstrap run workflow.yml \
--remote-node prod=https://prod.example.com \
--remote-auth prod=admin:secret123
# Multiple remote nodes with API key
merobox bootstrap run workflow.yml \
--remote-node prod=https://prod.example.com \
--remote-node staging=https://staging.example.com \
--api-key sk-default-key
Resource Management
Commands for installing applications, managing contexts, and handling identities directly (outside workflows).
merobox install
Install a WASM application on a Calimero node.
merobox install [OPTIONS]
Options:
--node, -n TEXT Node name to install on required
--url TEXT URL to install the application from
--path PATH Local path for dev installation
--dev Install as development application from local path
--metadata TEXT Application metadata (optional)
--timeout INTEGER Installation timeout in seconds (default: 30)
--verbose, -v Show verbose output
Options:
--node, -n TEXT Node name to install on required
--url TEXT URL to install the application from
--path PATH Local path for dev installation
--dev Install as development application from local path
--metadata TEXT Application metadata (optional)
--timeout INTEGER Installation timeout in seconds (default: 30)
--verbose, -v Show verbose output
Examples
merobox install --node my-node --url https://example.com/app.wasm
merobox install --node my-node --path ./app.wasm --dev
merobox install --node my-node --path ./app.wasm --dev
merobox application
Manage installed applications on Calimero nodes.
merobox application <SUBCOMMAND>
Subcommands:
list List all installed applications on a node
Subcommands:
list List all installed applications on a node
application list
merobox application list --node NODE_NAME [OPTIONS]
Options:
--node, -n TEXT Node name to list apps from required
--verbose, -v Show verbose output including full API response
Options:
--node, -n TEXT Node name to list apps from required
--verbose, -v Show verbose output including full API response
merobox context
Manage blockchain contexts on Calimero nodes.
merobox context <SUBCOMMAND>
Subcommands:
create Create a new context
list List all contexts on a node
show Show details of a specific context
Subcommands:
create Create a new context
list List all contexts on a node
show Show details of a specific context
context create
merobox context create [OPTIONS]
Options:
--node, -n TEXT Node name required
--application-id, -a TEXT Application ID required
--protocol, -p TEXT Protocol type (only "near" supported)
--params TEXT Init parameters as JSON string
--verbose, -v Show verbose output
Options:
--node, -n TEXT Node name required
--application-id, -a TEXT Application ID required
--protocol, -p TEXT Protocol type (only "near" supported)
--params TEXT Init parameters as JSON string
--verbose, -v Show verbose output
context list
merobox context list --node NODE_NAME [--verbose]
context show
merobox context show --node NODE_NAME --context-id CONTEXT_ID [--verbose]
Examples
merobox context create --node my-node --application-id app-123
merobox context create --node my-node --application-id app-123 --params '{"key": "value"}'
merobox context list --node my-node
merobox context show --node my-node --context-id ctx-456
merobox context create --node my-node --application-id app-123 --params '{"key": "value"}'
merobox context list --node my-node
merobox context show --node my-node --context-id ctx-456
merobox identity
Manage cryptographic identities on Calimero nodes.
merobox identity <SUBCOMMAND>
Subcommands:
generate Generate a new identity
list List identities on a node
show Show identity details
Subcommands:
generate Generate a new identity
list List identities on a node
show Show identity details
Direct Interaction
Commands for calling contract methods and joining contexts directly from the CLI.
merobox call
Execute smart contract functions via JSON-RPC.
merobox call [OPTIONS] NODE_NAME CONTEXT_ID METHOD [ARGS]...
Arguments:
NODE_NAME Target node name required
CONTEXT_ID Context ID to call within required
METHOD Method name to invoke required
ARGS Method arguments (optional)
Options:
--executor-key TEXT Executor public key for signing
--exec-type TEXT Execution type
Arguments:
NODE_NAME Target node name required
CONTEXT_ID Context ID to call within required
METHOD Method name to invoke required
ARGS Method arguments (optional)
Options:
--executor-key TEXT Executor public key for signing
--exec-type TEXT Execution type
merobox join
Join a blockchain context using an invitation payload.
merobox join NODE_NAME CONTEXT_ID INVITEE_ID INVITATION
Arguments:
NODE_NAME Node to join with required
CONTEXT_ID Context ID to join required
INVITEE_ID Public key of joining identity required
INVITATION Invitation payload required
Arguments:
NODE_NAME Node to join with required
CONTEXT_ID Context ID to join required
INVITEE_ID Public key of joining identity required
INVITATION Invitation payload required
Remote Node Management
Register, authenticate with, and manage remote Calimero nodes.
merobox remote
merobox remote <SUBCOMMAND> [OPTIONS]
Subcommands:
register Register a remote node
unregister Remove a registered node
login Authenticate with a remote node
logout Remove cached authentication
status Show registered nodes and cached tokens
test Test connectivity and authentication
list List registered remote nodes
Subcommands:
register Register a remote node
unregister Remove a registered node
login Authenticate with a remote node
logout Remove cached authentication
status Show registered nodes and cached tokens
test Test connectivity and authentication
list List registered remote nodes
remote register
merobox remote register <name> <url> [OPTIONS]
Options:
--auth-method, -m TEXT Auth method: user_password, api_key, none
--username, -u TEXT Username for user_password auth
--description, -d TEXT Human-readable description
Options:
--auth-method, -m TEXT Auth method: user_password, api_key, none
--username, -u TEXT Username for user_password auth
--description, -d TEXT Human-readable description
remote unregister
merobox remote unregister <name> [OPTIONS]
Options:
--remove-token Also remove cached authentication token
Options:
--remove-token Also remove cached authentication token
remote login
merobox remote login <url_or_name> [OPTIONS]
Options:
--username, -u TEXT Username (prompts if not provided)
--password, -p TEXT Password (prompts if not provided)
--api-key, -k TEXT API key for api_key auth method
--method, -m TEXT Auth method override
Options:
--username, -u TEXT Username (prompts if not provided)
--password, -p TEXT Password (prompts if not provided)
--api-key, -k TEXT API key for api_key auth method
--method, -m TEXT Auth method override
remote logout
merobox remote logout <url_or_name>
merobox remote logout --all # Remove all cached tokens
merobox remote logout --all # Remove all cached tokens
remote test
merobox remote test <url_or_name> [OPTIONS]
Options:
--username, -u TEXT Username for testing
--password, -p TEXT Password for testing
--api-key, -k TEXT API key for testing
Options:
--username, -u TEXT Username for testing
--password, -p TEXT Password for testing
--api-key, -k TEXT API key for testing
Tests: 1) Network connectivity, 2) Auth requirement detection, 3) Authentication, 4) API access verification.
remote status & list
merobox remote status # Nodes + cached tokens with expiry
merobox remote list # Registered remote nodes
merobox remote list # Registered remote nodes
Examples
# Register and authenticate
merobox remote register prod https://prod.example.com -m user_password -u admin
merobox remote login prod
# API key auth
merobox remote register staging https://staging.example.com -m api_key
merobox remote login staging -k sk-your-api-key
# Test and manage
merobox remote test prod
merobox remote status
merobox remote logout prod
merobox remote unregister prod --remove-token
merobox remote register prod https://prod.example.com -m user_password -u admin
merobox remote login prod
# API key auth
merobox remote register staging https://staging.example.com -m api_key
merobox remote login staging -k sk-your-api-key
# Test and manage
merobox remote test prod
merobox remote status
merobox remote logout prod
merobox remote unregister prod --remove-token
Environment Variables
Environment variables that control merobox behavior. Set via export VAR=value or inline before commands.
# Docker & Image
CALIMERO_IMAGE Docker image for Calimero nodes
DOCKER_HOST Docker daemon connection string
# Logging
LOG_LEVEL Logging level: DEBUG, INFO, WARNING, ERROR
RUST_BACKTRACE Rust backtrace level: 0, 1, full
# Frontend caching
CALIMERO_AUTH_FRONTEND_FETCH Set to "0" for cached auth frontend (default: "1")
CALIMERO_WEBUI_FETCH Set to "0" for cached WebUI frontend (default: "1")
# Authentication credentials
MEROBOX_USERNAME Default username for user_password auth
MEROBOX_PASSWORD Default password for user_password auth
MEROBOX_API_KEY Default API key for api_key auth
CALIMERO_IMAGE Docker image for Calimero nodes
DOCKER_HOST Docker daemon connection string
# Logging
LOG_LEVEL Logging level: DEBUG, INFO, WARNING, ERROR
RUST_BACKTRACE Rust backtrace level: 0, 1, full
# Frontend caching
CALIMERO_AUTH_FRONTEND_FETCH Set to "0" for cached auth frontend (default: "1")
CALIMERO_WEBUI_FETCH Set to "0" for cached WebUI frontend (default: "1")
# Authentication credentials
MEROBOX_USERNAME Default username for user_password auth
MEROBOX_PASSWORD Default password for user_password auth
MEROBOX_API_KEY Default API key for api_key auth
Credential Resolution Order
For remote node authentication, credentials are resolved in this priority:
1. CLI flags --password, -p / --api-key, -k
2. Environment variables MEROBOX_PASSWORD / MEROBOX_API_KEY
3. Interactive prompt Secure password input
2. Environment variables MEROBOX_PASSWORD / MEROBOX_API_KEY
3. Interactive prompt Secure password input
Usage Examples
# Use cached frontends
export CALIMERO_AUTH_FRONTEND_FETCH=0
export CALIMERO_WEBUI_FETCH=0
merobox run --auth-service --count 2
# Pre-set credentials for non-interactive use
export MEROBOX_USERNAME=admin
export MEROBOX_PASSWORD=secret
merobox remote login prod-node # No prompts
# Inline for single command
CALIMERO_WEBUI_FETCH=0 merobox run --count 2
export CALIMERO_AUTH_FRONTEND_FETCH=0
export CALIMERO_WEBUI_FETCH=0
merobox run --auth-service --count 2
# Pre-set credentials for non-interactive use
export MEROBOX_USERNAME=admin
export MEROBOX_PASSWORD=secret
merobox remote login prod-node # No prompts
# Inline for single command
CALIMERO_WEBUI_FETCH=0 merobox run --count 2
Global Options
merobox [OPTIONS] COMMAND [ARGS]...
--version Show version and exit
--help Show help message and exit
--version Show version and exit
--help Show help message and exit
Token Caching
Authentication tokens are automatically cached at ~/.merobox/auth_cache/ with restrictive permissions (0o600). Tokens are refreshed automatically on 401 responses.
# Token lifecycle
merobox remote login prod-node -u admin -p secret # Caches token
merobox bootstrap run workflow.yml # Uses cache
merobox remote status # Check expiry
merobox remote logout prod-node # Clear cache
merobox remote login prod-node -u admin -p secret # Caches token
merobox bootstrap run workflow.yml # Uses cache
merobox remote status # Check expiry
merobox remote logout prod-node # Clear cache