Metadata-Version: 2.5
Name: margo-tooling
Version: 0.9.0
Summary: Developer CLI for building and publishing Margo application packages
Project-URL: Homepage, https://github.com/karnarokEpoch/margot
Project-URL: Documentation, https://karnarokepoch.github.io/margot/
Project-URL: Repository, https://github.com/karnarokEpoch/margot
Project-URL: Issues, https://github.com/karnarokEpoch/margot/issues
Project-URL: Changelog, https://github.com/karnarokEpoch/margot/releases
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: docker>=7.2.0
Requires-Dist: dynaconf>=3.2.10
Requires-Dist: jinja2>=3.1
Requires-Dist: linkml>=1.11.1
Requires-Dist: oras>=0.2.28
Requires-Dist: podman>=5.8.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=14.0.0
Requires-Dist: semver>=3.0.4
Requires-Dist: typer>=0.15.4
Description-Content-Type: text/markdown

# margot

[![PyPI version](https://img.shields.io/pypi/v/margo-tooling)](https://pypi.org/project/margo-tooling/)
[![Python versions](https://img.shields.io/pypi/pyversions/margo-tooling)](https://pypi.org/project/margo-tooling/)
[![License](https://img.shields.io/pypi/l/margo-tooling)](https://github.com/karnarokEpoch/margot/blob/main/LICENSE)
[![CI](https://img.shields.io/github/actions/workflow/status/karnarokEpoch/margot/ci.yml)](https://github.com/karnarokEpoch/margot/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://karnarokepoch.github.io/margot/)
[![Downloads](https://img.shields.io/pypi/dm/margo-tooling)](https://pypi.org/project/margo-tooling/)
[![Container](https://img.shields.io/badge/ghcr.io-margot-blue?logo=podman)](https://github.com/karnarokEpoch/margot/pkgs/container/margot)
[![Codecov](https://img.shields.io/codecov/c/github/karnarokEpoch/margot)](https://codecov.io/gh/karnarokEpoch/margot)
[![GitHub stars](https://img.shields.io/github/stars/karnarokEpoch/margot)](https://github.com/karnarokEpoch/margot)
[![GitHub forks](https://img.shields.io/github/forks/karnarokEpoch/margot)](https://github.com/karnarokEpoch/margot)
[![GitHub issues](https://img.shields.io/github/issues/karnarokEpoch/margot)](https://github.com/karnarokEpoch/margot/issues)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![pytest](https://img.shields.io/badge/tested%20with-pytest-blue)](https://docs.pytest.org/)

**margot** is a developer CLI for building and publishing [Margo](https://margo.org) application
packages as OCI artifacts. It handles packaging, tagging, and pushing/pulling to any
OCI-compliant registry.

[Documentation](https://karnarokepoch.github.io/margot/) ·
[PyPI](https://pypi.org/project/margo-tooling/)

## Install

### From PyPI

```bash
pip install margo-tooling
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv tool install margo-tooling
```

Or with [pipx](https://pipx.pypa.io/latest/index.html):

```bash
pipx install margo-tooling
```

### With a container

Every release publishes a container image to GHCR. Mount your project directory into
`/workspace`:

```bash
podman run --rm -v "$PWD":/workspace ghcr.io/karnarokepoch/margot:latest --help
```

Pin to a specific version instead of `latest` for reproducible builds, e.g.
`ghcr.io/karnarokepoch/margot:1.0.0`.

### From source

```bash
git clone https://github.com/karnarokEpoch/margot.git
cd margot
uv sync
```

## Usage

```
$ margot --help

 Usage: margot [OPTIONS] COMMAND [ARGS]...

 Margo application package developer CLI.

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --version             -V        Print version and exit.                     │
│ --verbose             -v        Enable verbose output (step-level info).     │
│ --debug               -d        Enable debug output (infra-level detail,     │
│                                  implies --verbose).                         │
│ --install-completion            Install completion for the current shell.    │
│ --show-completion                Show completion for the current shell, to  │
│                                  copy it or customize the installation.      │
│ --help                -h        Show this message and exit.                 │
╰────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────╮
│ fetch     Fetch and display the manifest of an OCI artifact.                  │
│ build     Build Margo application package types locally.                     │
│ push      Push built Margo application artifacts to an OCI registry.         │
│ pull      Pull OCI artifact layers to a local directory.                     │
│ package   Bundle built artifacts into an offline .tgz for disconnected      │
│           deployment.                                                        │
│ verify    Validate the Margo application description against the Margo spec │
│           schema.                                                            │
│ describe  Describe a Margo application description in rich, structured      │
│           output.                                                           │
│ auth      Manage OCI registry credentials.                                  │
╰────────────────────────────────────────────────────────────────────────────────╯
```

### A minimal project

A Margo project is described by a `margo.yaml` file at the project root:

```
nginx-helm/
├── margo.yaml
└── margo/
    └── app.yaml.jinja
```

```yaml
# margo.yaml
apiVersion: v1
id: com-example-nginx
name: nginx
version: "1.0.0"
appVersion: "1.27.0"
description: "NGINX web server deployed via Helm chart"
repository: public.ecr.aws/g2n4p2m7/margo
```

### Validate the application description

```bash
margot verify
```

Validates `app.yaml` (or `app.yaml.jinja`, rendered on the fly) against the upstream
Margo spec schema — no network access, no prior build required.

### Inspect it visually

```bash
margot describe
```

Renders the descriptor as structured panels and trees: identity, deployment profiles,
configuration (settings, schemas, parameters), and extensions.

### Build and push

```bash
margot build
margot push
```

`build` renders the descriptor and stages it under `build_dir`. `push` publishes the
artifact via [ORAS](https://oras.land/) to the registry declared in `margo.yaml`,
tagged with `version`:

```
public.ecr.aws/g2n4p2m7/margo:1.0.0
```

Log in first if the registry requires auth:

```bash
margot auth login
```

### Package for offline delivery

```bash
margot build
margot package
```

`package` collects everything `build` produced and bundles it into a single
`<id>-<version>.tgz` — for deployment in disconnected environments without registry
access. The bundle is written to `.dist/<version>/` by default:

```
.dist/1.0.0/com-example-nginx-1.0.0.tgz
```

Pass `--output` to write it elsewhere. A bundle is never pushed to a registry.

### Pull and inspect a published artifact

```bash
margot pull public.ecr.aws/g2n4p2m7/margo:1.0.0 --output ./out
margot fetch public.ecr.aws/g2n4p2m7/margo:1.0.0
```

`pull` writes the artifact's layers to disk as-is (no extraction). `fetch` prints the
raw manifest JSON for a quick remote inspection, without pulling anything.

### Shell completion

Enable shell tab completion for margot commands and flags:

```bash
# Quick setup — appends to your shell's rc file directly
margot --install-completion

# Manual setup — prints the script; redirect it wherever you source completions from
margot --show-completion bash > ~/.local/share/bash-completion/completions/margot
```

Both methods require a shell restart or re-sourcing the rc file to take effect.
`--show-completion` takes a shell argument (`bash`, `zsh`, `fish`, `powershell`, or `pwsh`)
and prints the completion script to stdout.

`--install-completion` has no `--path` option — it always appends to the shell's default rc file (e.g. `~/.bashrc`).
If you curate your own rc includes rather than a raw rc append, use
`--show-completion` instead and redirect the output to your preferred location.

## Learn more

- [Documentation](https://karnarokepoch.github.io/margot/) — full command reference,
  `margo.yaml` reference, configuration, and worked examples (Helm, Compose, Quadlet, multi-component).
- [ROADMAP.md](ROADMAP.md) — planned features, fixes, and ideas.
- [CONTRIBUTING.md](CONTRIBUTING.md) — development setup, testing, release process.
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — community standards.

## License

[Apache License 2.0](LICENSE)
