Merobox CLI
A Python CLI for managing Calimero nodes (Docker or native) and orchestrating YAML workflows.
Full documentation: https://calimero-network.github.io/merobox/
Quick Start
Installation
PyPI (recommended):
pipx install merobox
From source:
git clone https://github.com/calimero-network/merobox.git
cd merobox
pipx install -e .
Basic Usage
# Start Calimero nodes
merobox run --count 2
# Start with auth service (Docker mode)
merobox run --auth-service
# Start with embedded auth (binary mode)
merobox run --no-docker --binary-path /path/to/merod --auth-mode embedded
# Pass extra arguments straight to `merod run` (binary mode only)
merobox bootstrap run workflow.yml --no-docker --binary-path ./merod \
--merod-args="--sync-strategy delta --state-sync-strategy hash"
# Check node status
merobox health
# Execute a workflow
merobox bootstrap run workflow.yml
# Stop all nodes
merobox stop --all
Example Workflow
name: "Hello World"
nodes:
count: 2
prefix: "node"
steps:
- name: "Install App"
type: "install_application"
node: "node-1"
path: "./app.mpk"
outputs:
app_id: applicationId
- name: "Create Context"
type: "create_context"
node: "node-1"
application_id: "{{app_id}}"
outputs:
ctx_id: contextId
- name: "Call Method"
type: "call"
node: "node-1"
context_id: "{{ctx_id}}"
method: "hello"
Features
- Node Management — Start, stop, and monitor nodes in Docker or as native processes
- Workflow Orchestration — ~100 step types for complex multi-step YAML workflows
- Remote Nodes — Connect to remote Calimero nodes with user/password or API key auth
- Auth Integration — Traefik proxy (Docker) or embedded JWT auth (binary mode)
- Fuzzy Testing — Long-duration randomized load tests with weighted operations
- pytest Integration —
cluster()andworkflow()context managers for test harnesses
Requirements
- Python: 3.9 – 3.11 (3.12+ not supported due to
py-near/ed25519dependency) - Docker: 20.10+ (for Docker mode)
- OS: Linux, macOS (Windows via WSL only)
Documentation
All detailed documentation lives in the Documentation:
| Topic | Page |
|---|---|
| System architecture & data flow | System Overview |
| WorkflowExecutor, BaseStep, step factory | Workflow Engine |
| DockerManager, BinaryManager, Traefik | Node Management |
| Remote node CLI & auth methods | Remote Nodes |
| Complete YAML schema & all step types | Workflow YAML |
| All CLI commands with flags & options | CLI Reference |
| MeroboxError hierarchy, retry patterns | Error Handling |
| cluster(), workflow(), pytest fixtures | Testing Guide |
| Common issues & debugging tips | Troubleshooting |
| Terms & definitions | Glossary |
Release Process
# Update version in ONE place
vim merobox/__init__.py # Change __version__ = "X.Y.Z"
# Commit and push — automation handles tagging, builds, GitHub release, and PyPI
git add merobox/__init__.py
git commit -m "chore: bump version to X.Y.Z"
git push origin master
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
See the Testing Guide for development setup and adding new commands/step types.
License
MIT — see LICENSE for details.
Links
1 maintainer
Metadata
1 maintainer
Release files for merobox 0.6.81
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| merobox-0.6.81.tar.gz | 365.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| merobox-0.6.81-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 792.2 kB
Release files / merobox-0.6.81.tar.gz
| Download URL | merobox-0.6.81.tar.gz |
|---|---|
| Size | 365.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
66b511ed602fb83affbfed300c88982d0fe06d91b5dde46d2da9a086ac1c33be
|
|
BLAKE2b-256 checksum How to use checksums |
215650e14708b268f1620472b094e36b7e25f1834ae0eace25d1fac15116ba18
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency logRelease files / merobox-0.6.81-py3-none-any.whl
| Download URL | merobox-0.6.81-py3-none-any.whl |
|---|---|
| Size | 426.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2a707eca2b5aeab5d2fcbec5a8aef02ec4f3a21a89b5db7726b65318148bf73c
|
|
BLAKE2b-256 checksum How to use checksums |
b4e05c993fd3bae695c3afaef42e349e73be6d12917e7ab885be19ea211a35ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 29, 2026.
Transparency log
