Maddex CLI

Maddex is a zero-build CLI that installs Caspian-ready UI components (Python) into your project—similar in spirit to how shadcn-style CLIs “copy in” components, but for a Caspian/Python component workflow.

It pulls components from the Maddex component registry API and writes them directly into your repository (e.g., src/lib/maddex). It can also bootstrap baseline styling and icons so a fresh project is ready to use immediately.

What it does

• Adds components on demand: maddex add Button Card downloads component code and writes it locally.
• Supports multi-file components: components can ship as multiple files (e.g., Button.py, Button.html) or as a single file (legacy protocol).
• Bulk install: maddex add --all installs the full component set.
• Updates installed components: maddex update scans your output directory for installed .py components and refreshes them from the registry.
• First-run bootstrap:
  • Creates maddex.json with sensible defaults.
  • Copies a bundled globals.css into your app (src/app/globals.css) if missing (or on first run).
  • Ensures tw-animate-css is installed (as a dev dependency).
  • Installs a default set of icons via ppicons and writes them to src/lib/ppicons.

Requirements

• Node.js 18+ recommended
• A project with:
  • package.json
  • Typical Caspian layout assumptions:
    • src/app/globals.css
    • src/lib/* for generated libraries (default output)

Install

Globally via npm:

npm i -g maddex

Local via npm:

npm i -D maddex

Or run via npx:

npx maddex add Button

Quick start

Add one or more components

maddex add Button Card

Interactive add:

maddex add

Install everything

maddex add --all

Update what’s already installed

maddex update

Flags

| Flag | Works with | Meaning | | --------- | ---------: | ------------------------------------------------------------------ | | --all | add | Install every component from the registry | | --force | add | Overwrite existing files (also enabled automatically on first run) |

Output location

Default:

src/lib/maddex

Configuration (maddex.json)

Created on first run. Default shape:

{
  "style": "default",
  "force": false,
  "outputDir": "src/lib/maddex",
  "iconsInstalled": false,
  "tailwind": {
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "pythonPath": "src/lib/maddex",
  "iconLibrary": "ppicons"
}

First-run behavior

When maddex.json does not exist yet, Maddex will:

1. Create maddex.json.
2. Install default icons (one-time) via:
   • npm install -g ppicons
   • npx ppicons add <icon list>
3. Copy bundled globals.css to src/app/globals.css if missing.
4. Ensure tw-animate-css is installed in devDependencies.
5. Ensure core components exist (unless --all):
   • Slot
   • Portal
   • utils

Registry API

• Single component: https://maddex.tsnc.tech/cli?component=<Name>
• All components: https://maddex.tsnc.tech/cli?component=all

Payloads supported

Multi-file payload:

{
  "name": "Button",
  "files": [
    { "name": "Button.py", "content": "..." },
    { "name": "Button.html", "content": "..." }
  ]
}

Legacy single-file payload:

{
  "name": "Button",
  "content": "...python code..."
}

Troubleshooting

• “No components found to update.”: update only scans .py files in outputDir and ignores __init__.py.
• Icon install fails: ensure you can install global npm packages and run npx.

📄 License

maddex-cli is released under the MIT License. See LICENSE for details.

👤 Author

This project is developed and maintained by The Steel Ninja Code, continuously pushing the boundaries of Python development.

📧 Contact

Questions or feedback? Reach us at [email protected] — we’d love to hear from you!

Credits

• Component registry: maddex.tsnc.tech
• Icons workflow: ppicons