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.wasm"
    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() and workflow() context managers for test harnesses

Requirements

Python: 3.9 – 3.11 (3.12+ not supported due to py-near / ed25519 dependency)
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.

Release files for merobox 0.6.73

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for merobox 0.6.73
File	Size	Uploaded
merobox-0.6.73.tar.gz	357.6 kB	Sep 2, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for merobox 0.6.73
File	Interpreter	ABI	Platform	Reset
merobox-0.6.73-py3-none-any.whl 418.3 kB Sep 2, 2026	Python 3	none	any	Details

Total release size: 775.9 kB

Release files / merobox-0.6.73.tar.gz

Download URL	merobox-0.6.73.tar.gz
Size	357.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`670c1530ebbf8b3b3d41194441a126c5c4b566c5c74615436134cc0c3a26972b`
BLAKE2b-256 checksum How to use checksums	`68c98f18e7d6652e69303304d50ecc8128b6e275f7db8d005f09e88410170922`
Upload date	Sep 2, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/calimero-network/merobox
Publishing commit: github.com/calimero-network/merobox/tree/b3c645ca8c80074aaa5e12a3254957ecd996f5e6

Workflow

Publishing configuration: github.com/calimero-network/merobox/blob/b3c645ca8c80074aaa5e12a3254957ecd996f5e6/.github/workflows/release.yml
Publishing logs: github.com/calimero-network/merobox/actions/runs/33604835932/attempts/1

Artifact

Subject: merobox-0.6.73.tar.gz
SHA-256 checksum: 670c1530ebbf8b3b3d41194441a126c5c4b566c5c74615436134cc0c3a26972b Verifying attestations

Release files / merobox-0.6.73-py3-none-any.whl

Download URL	merobox-0.6.73-py3-none-any.whl
Size	418.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7b9970242175ef1accc084d78ebe22d4e38e7e5872c0e6b6f39653455dd499ff`
BLAKE2b-256 checksum How to use checksums	`c68a8825958e167fb7171ad24fa93c2d1cd478a917370f4c9e8990944542a2c3`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/calimero-network/merobox
Publishing commit: github.com/calimero-network/merobox/tree/b3c645ca8c80074aaa5e12a3254957ecd996f5e6

Workflow

Publishing configuration: github.com/calimero-network/merobox/blob/b3c645ca8c80074aaa5e12a3254957ecd996f5e6/.github/workflows/release.yml
Publishing logs: github.com/calimero-network/merobox/actions/runs/33604835932/attempts/1

Artifact

Subject: merobox-0.6.73-py3-none-any.whl
SHA-256 checksum: 7b9970242175ef1accc084d78ebe22d4e38e7e5872c0e6b6f39653455dd499ff Verifying attestations