Skip to main content

mad-cli

PyPI CI Python

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)

Source distribution for mad-cli 0.4.0
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)

Table of built distributions (wheels) for mad-cli 0.4.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page