mad-cli
Operator CLI for Mad. mad-cli installs, runs and
manages mad-edge containers — the Mad runtime that provisions isolated workspaces and
launches autonomous coding agents (Claude Code, OpenCode, …) against your repositories.
mad-cli is the thing an operator installs on a server or a Raspberry Pi. It does not
run agents itself: it generates a Dockerfile, a compose.yml and a .env, builds the
image and drives the container lifecycle through Docker Compose. The agent runtime lives in
the mad-edge package, which is installed inside the
container.
Alpha (0.x). Interfaces may change between minor releases. Pin a version in production.
Quickstart
pip install mad-cli
# Guided install: generates the config, builds the image, starts the container.
mad install
# Day-to-day lifecycle.
mad start # build + up (detached)
mad status # container state + API health
mad logs # follow logs
mad stop # stop, keeping workspace data on the host
mad install walks you through the instance name, host port, data path, GitHub token,
git identity and Claude OAuth token, then writes everything under ~/.config/mad (override
with MAD_CLI_CONFIG_DIR) and starts the container. Once it is healthy the Mad HTTP/MCP API
is available on the port you chose.
Commands
The surface grows across the early minor releases; everything below the current line is planned.
| Command | Since | What it does |
|---|---|---|
mad install |
v0.1 | Guided setup: render config, build image, start the container. |
mad start / stop / restart |
v0.1 | Container lifecycle (up --build / down / down+up). |
mad status |
v0.1 | Container state and API health for an instance. |
mad logs |
v0.1 | Follow container logs. |
mad shell |
v0.1 | Open an interactive bash shell inside the container. |
mad list |
v0.2 | List every configured instance. |
mad info NAME |
v0.2 | Show one instance's resolved config. |
mad keys |
v0.2 | Set, rotate and mask API keys / tokens in .env. |
mad config |
v0.2 | Read and edit .env values safely. |
mad versions / update |
v0.3 | Show the latest published mad-edge and rebuild onto it. |
mad serve / service |
v0.4 | Run the local HTTP API, or install it as a background service. |
Instance-scoped commands take an optional INSTANCE argument; when exactly one instance is
configured it is used by default.
HTTP API (optional)
Every CLI capability is also exposed over a local HTTP API so a UI/dashboard can build on the same logic. It ships as an optional extra so the base CLI stays a two-dependency package (typer + rich):
pip install 'mad-cli[server]'
mad serve # foreground API on http://127.0.0.1:7373
The API binds 127.0.0.1 by default and requires a bearer token (auto-generated at
~/.config/mad/api-token, mode 0600) on every request except /health. Secret values are
always masked on reads. OpenAPI is served at /openapi.json, docs at /docs. See
docs/03-contracts/http-api.md.
To keep it running across reboots:
mad service install # systemd user unit (Linux) / launchd LaunchAgent (macOS)
If the server extra is not installed, mad service install auto-provisions a dedicated
virtualenv under ~/.config/mad/server-venv and installs the API there (use --wheel PATH
to install from a local artifact instead of PyPI), then points the service at it — the base
CLI never needs FastAPI in its own environment.
MVP limitation. Long operations (install with start,
start,update) run synchronously — the request blocks until the Docker build and health wait finish. Background jobs are a future enhancement.
How it relates to mad-edge
mad-cli (this package) |
mad-edge |
|
|---|---|---|
| Runs on | the operator's host | inside the container |
| Console script | mad |
mad-edge (server) |
| Role | install & lifecycle management | the agent runtime / HTTP + MCP API |
| Talks to | Docker, the filesystem, PyPI | Claude Code, OpenCode, GitHub, workspaces |
mad-cli pins or tracks the mad-edge version through the generated Dockerfile; the
container installs mad-edge from PyPI at build time. Version bumps follow the mad-edge
versioning policy.
License
MIT.
Metadata
Release files for mad-cli 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mad_cli-0.4.0.tar.gz | 120.1 kB | With provenance | Details for mad_cli-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mad_cli-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for mad_cli-0.4.0-py3-none-any.whl |
Total release size: 190.8 kB
Release files / mad_cli-0.4.0.tar.gz
| Download URL | mad_cli-0.4.0.tar.gz |
|---|---|
| Size | 120.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
72bd02379321644bfead301d9047d5051131d4310f4bfb5e312fb0b9de444db6
|
|
BLAKE2b-256 checksum How to use checksums |
2519a7e4fb9d60a8420260523a012fbac609329e25fb5d26132685edf9211475
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 5, 2026.
Transparency logRelease files / mad_cli-0.4.0-py3-none-any.whl
| Download URL | mad_cli-0.4.0-py3-none-any.whl |
|---|---|
| Size | 70.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
abbdf7675f85789dabe4db485febbadb14f24b2255f7a22649dc12fad1875000
|
|
BLAKE2b-256 checksum How to use checksums |
3f0bf03c24e170d915eee55dc0dfaf2ebdad598dd13af7db369087c245530cef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Jul 5, 2026.
Transparency logSecurity for mad-cli 0.4.0
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mad_cli-0.4.0.tar.gz
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 Jul 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.