Metadata-Version: 2.4
Name: helm-me
Version: 0.2.1
Summary: Kubernetes app CLI and DSL for fast prototyping, deployment, day-2 operations, and later Helm export.
Project-URL: Homepage, https://teserak.github.io/helm-me/
Project-URL: Documentation, https://teserak.github.io/helm-me/
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,deployment,developer-experience,devops,dsl,helm,k8s,kubernetes,platform-engineering,python,yaml
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: tomli-w>=1.0.0
Provides-Extra: tui
Requires-Dist: textual>=0.50.0; extra == 'tui'
Description-Content-Type: text/markdown

# helm-me

[![CI](https://github.com/teserak/helm-me/actions/workflows/ci.yml/badge.svg)](https://github.com/teserak/helm-me/actions/workflows/ci.yml)
[![Docs](https://github.com/teserak/helm-me/actions/workflows/docs.yml/badge.svg)](https://github.com/teserak/helm-me/actions/workflows/docs.yml)
[![PyPI version](https://img.shields.io/pypi/v/helm-me.svg)](https://pypi.org/project/helm-me/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/helm-me.svg)](https://pypi.org/project/helm-me/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
[![Release](https://img.shields.io/github/v/release/teserak/helm-me?display_name=tag)](https://github.com/teserak/helm-me/releases)

> [!WARNING]
> `helm-me` is currently in beta. Core workflows are usable, but the CLI surface, YAML schema, Python DSL, and some generated output details may still change significantly between releases.

Define, deploy, and operate Kubernetes apps with a fast, developer-friendly workflow.

`helm-me` is aimed at developers who want to ship prototypes and internal apps to Kubernetes quickly, without spending more time on chart authoring than on the application itself. It provides a simple app spec in YAML or Python, operational commands for day-2 work, and a path to export a Helm chart when the project grows up.

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

`helm-me` sits between raw manifests, repetitive `kubectl` command sequences, and full Helm chart authoring. It focuses on developer experience: simple app definitions, fast deploys, convenient shell/log/copy workflows, and compatibility with Helm-oriented environments.

## 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.
- Avoid memorizing long `kubectl` command sequences for common day-2 tasks.
- Keep moving fast during prototyping, then export to a Helm chart when you need a more standard handoff.

## What problem does it solve?

For many small and medium projects, the first Kubernetes deployment is blocked less by the app itself and more by surrounding work:

- writing and maintaining Helm charts
- wiring together repetitive manifests
- remembering operational `kubectl` commands
- dealing with awkward workflows around minimal or distroless containers

`helm-me` tries to make Kubernetes feel like a higher-level application workflow: define the app once, deploy it quickly, inspect it with one CLI, and keep an upgrade path to Helm when needed.

## When to use it

Use `helm-me` when:

- you want a simpler app workflow on Kubernetes
- you want to deploy prototypes, internal tools, demos, chats, APIs, or frontend apps quickly
- you want one tool for both deploys and common operational commands
- you want YAML for simple cases and Python when you need parameters or reuse
- you want a path to export a Helm chart later instead of writing one first

Avoid `helm-me` when:

- you specifically need the full Helm chart packaging and authoring model from day one
- you want GitOps reconciliation to be the primary operating model
- you are building a Kubernetes Operator rather than defining an application
- your team already has a strong, standardized chart platform and does not need a higher-level app workflow

## Comparison

Compared with raw manifests:

- `helm-me` gives you a higher-level app spec, reusable components, and operational commands in one place

Compared with Helm:

- `helm-me` optimizes for developer speed and lower setup overhead during prototyping, while still keeping a path to export a chart later

Compared with plain `kubectl` workflows:

- `helm-me` reduces command memorization and wraps common day-2 tasks such as logs, shell, exec, copy, and port-forward behind app-aware commands

## Prerequisites

Before you start, make sure you have:

- **Python `3.11+`** installed
- **`kubectl`** installed (used for interactive commands such as `shell`, `exec`, `cp`, and `port-forward`)
- A working **Kubeconfig** (e.g., from `kind`, `minikube`, `k3d`, or a remote cluster)

## 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
```

> **What you should see**: `helm-me deploy` will render the manifests, create the namespace if it doesn't exist, build constraints, save the deployment in a local registry, and wait for pods to become ready.

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
```

See the [Getting Started guide](https://teserak.github.io/helm-me/getting-started/first-app/) for the full walkthrough, including a Python DSL example and importing existing deployments.

## Project status

`helm-me` is currently in beta. It is already useful for real prototyping and internal deployments, but you should expect some evolution in command naming, schema details, Python DSL helpers, and generated output.

## Common Tasks

| Task | Command |
| --- | --- |
| Validate a spec | `helm-me lint deploy.yaml` |
| Print rendered manifests | `helm-me render deploy.yaml` |
| Preview changes before deploy | `helm-me diff deploy.yaml` |
| Deploy an app | `helm-me deploy deploy.yaml --yes` |
| Re-deploy from registry | `helm-me update --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` |

## 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 the [API Reference](https://teserak.github.io/helm-me/reference/api/) for the field-level reference.

## Documentation

Full documentation is available at **[teserak.github.io/helm-me](https://teserak.github.io/helm-me/)**.

- [Getting Started](https://teserak.github.io/helm-me/getting-started/first-app/) — first deployment, first commands, and first import
- [Tutorial](https://teserak.github.io/helm-me/tutorial/deploy/) — deploy, ops, ingress, secrets, storage, local dev
- [Advanced](https://teserak.github.io/helm-me/advanced/cluster-config/) — namespace, kubeconfig, params, imports
- [API Reference](https://teserak.github.io/helm-me/reference/api/) — DSL and YAML reference for app fields, components, and helper constructors

## Examples

- [`examples/minimal/`](https://github.com/teserak/helm-me/tree/main/examples/minimal) — smallest possible app in Python and YAML
- [`examples/full/`](https://github.com/teserak/helm-me/tree/main/examples/full) — multi-component app with ingress, secrets, and SQLite storage
- [`examples/with_dbs/`](https://github.com/teserak/helm-me/tree/main/examples/with_dbs) — PostgreSQL + Redis + backend example

## FAQ

**Is this a Helm replacement?**
Not exactly. `helm-me` is better understood as a higher-level application workflow for teams that do not want to start with chart authoring. It can still fit Helm-oriented environments and can export a chart when needed.

**Why not just use raw manifests or `kubectl`?**
You can, but many teams lose time on repeated YAML structure, long operational commands, and ad hoc workflows around shell access, copying files, logs, and port-forwarding. `helm-me` tries to make those common tasks easier and more consistent.

**Why not just start with Helm?**
For mature platforms, Helm is often the right end state. But for prototypes, internal tools, demos, and fast-moving apps, chart authoring can become heavier than the app itself. `helm-me` is meant to reduce that early overhead without blocking a later move to Helm.

**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 [Advanced / Cluster Config](https://teserak.github.io/helm-me/advanced/cluster-config/).

**How do I target another cluster or context?**
Pass `--kubeconfig`, `--context`, and optionally `--namespace`. You can also save defaults in `.helm-me.toml`. See [Cluster Config](https://teserak.github.io/helm-me/advanced/cluster-config/).

**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 [Import Existing Deployments](https://teserak.github.io/helm-me/tutorial/import/).

`secretEnv`, inline secrets, SQLite volumes, PostgreSQL/Redis storage, and PVC uploads are covered in [Secrets & Environment](https://teserak.github.io/helm-me/tutorial/secrets/).
