Metadata-Version: 2.4
Name: helm-me
Version: 0.1.2
Summary: Python DSL and CLI for rendering and deploying simple Kubernetes apps.
Project-URL: Source Code, https://github.com/teserak/helm-me
Project-URL: Bug Tracker, https://github.com/teserak/helm-me/issues
Author: teserak
License: MIT
License-File: LICENSE
Keywords: cli,deploy,dsl,helm,k8s,kubernetes
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Requires-Dist: cyclopts>=2.9.9
Requires-Dist: kubernetes>=30.1.0
Requires-Dist: pydantic>=2.8
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: rich>=14.3.3
Requires-Dist: textual>=0.50.0
Requires-Dist: tomli-w>=1.0.0
Description-Content-Type: text/markdown

# helm-me

Define Kubernetes apps in Python or YAML, then deploy and operate them with one CLI.

`helm-me` is aimed at teams that want something lighter than a full Helm chart for day-to-day app deployments, but still want repeatable manifests, typed configuration, and operational commands such as `ops pods`, `ops logs`, `ops shell`, and `ops port-forward`.

![Main Demo](https://raw.githubusercontent.com/teserak/helm-me/main/demos/demo_main.gif)

## Why use it

- Write one app spec instead of hand-maintaining multiple Kubernetes manifests.
- Choose **YAML** for simple config-driven setups or **Python** for typed, parameterized specs.
- Use built-in components for `web`, `postgresql`, `redis`, and deploy hooks.
- Import existing deployments and manage them through the same CLI.
- Work with local dev clusters (`kind`, `minikube`, `k3d`) without pushing images first.

## Before you start

- Python `3.11+`
- Access to a Kubernetes cluster through a working kubeconfig
- `kubectl` for interactive commands such as `shell`, `exec`, `cp`, and `port-forward`

## Installation

Choose one of these flows:

```bash
# Run without installing
uvx helm-me --help

# Install as a user tool
uv tool install helm-me
helm-me --help

# Or add it to the current project
uv add helm-me
uv run helm-me --help
```

All examples below use `helm-me ...`.
If you installed it with `uv add`, run them as `uv run helm-me ...`.
If you use `uvx`, run them as `uvx helm-me ...`.
If you use `uv tool install`, run them exactly as shown.

## 5-Minute Quick Start

Create a minimal `deploy.yaml`:

```yaml
apiVersion: helm-me/v1alpha1
kind: Application
metadata:
  name: hello-app

components:
  backend:
    type: web
    image: traefik/whoami:latest
    port: 80
```

Validate, inspect, and deploy it:

```bash
helm-me lint deploy.yaml
helm-me render deploy.yaml
helm-me deploy deploy.yaml --namespace demo --yes
```

Check that it is running:

```bash
helm-me ops pods hello-app
helm-me ops logs backend hello-app --tail 50
helm-me ops port-forward backend 8080 hello-app
```

Open [docs/quickstart.md](docs/quickstart.md) for the full step-by-step guide, including a Python DSL example and importing an existing deployment.

## Common Tasks

| Task | Command |
| --- | --- |
| Validate a spec | `helm-me lint deploy.yaml` |
| Print rendered manifests | `helm-me render deploy.yaml` |
| Deploy an app | `helm-me deploy deploy.yaml --yes` |
| List pods | `helm-me ops pods <app>` |
| Show pods, services, and ingresses | `helm-me ops status <app>` |
| Stream logs | `helm-me ops logs <component> <app> -f` |
| Open interactive shell | `helm-me ops shell <component> <app>` |
| Scale a component | `helm-me ops scale <component> <replicas> <app>` |
| Select the active app | `helm-me app use <app>` |
| Import an existing deployment | `helm-me app import <name> --namespace <ns>` |
| Generate a spec from a live deployment | `helm-me app generate-spec <name> --fmt yaml --output deploy.yaml` |

## Which format should I choose?

Use **YAML** when:

- you want a simple declarative file
- non-Python users will maintain the spec
- you do not need dynamic parameters beyond static config

Use **Python** when:

- you want IDE autocomplete and type hints
- you need `param()`-based environment-driven configuration
- you prefer composing specs in code

Both formats support the same core concepts. See [docs/API.md](docs/API.md) for the field-level reference.

## Documentation Map

- [docs/quickstart.md](docs/quickstart.md) — first deployment, first commands, and first import
- [docs/advanced-settings.md](docs/advanced-settings.md) — namespace, kubeconfig, params, secrets, storage, imports, local dev
- [docs/API.md](docs/API.md) — DSL and YAML reference for app fields, components, and helper constructors

## Examples

- [`examples/minimal/`](examples/minimal/) — smallest possible app in Python and YAML
- [`examples/full/`](examples/full/) — multi-component app with ingress, secrets, and SQLite storage
- [`examples/with_dbs/`](examples/with_dbs/) — PostgreSQL + Redis + backend example

## What users usually ask next

**Which namespace will be used?**
If the spec sets `namespace`, that value is used. If not, the default namespace is the app name. `helm-me deploy --namespace ...` overrides the spec for that deploy. Full rules are in [docs/advanced-settings.md](docs/advanced-settings.md).

**How do I target another cluster or context?**
Pass `--kubeconfig`, `--context`, and optionally `--namespace`. You can also save defaults in `.helm-me.toml`. See [docs/advanced-settings.md](docs/advanced-settings.md).

**Can I manage something that was not deployed by helm-me?**
Yes. Use `helm-me app import ...`, optionally with `--label` when the app does not use standard labels. See [docs/quickstart.md](docs/quickstart.md#import-an-existing-deployment).

**How do secrets and storage work?**
`secretEnv`, inline secrets, SQLite volumes, PostgreSQL/Redis storage, and PVC uploads are covered in [docs/advanced-settings.md](docs/advanced-settings.md).
