# Piceli

> Piceli is Kubernetes infrastructure as typed Python: describe resources with Python templates, `kubernetes` client models or YAML/JSON, compute a reviewable plan against the live cluster, apply it only with an explicit approval of the plan hash, and resume, roll back and observe the result. It also records source identity, runs pinned containerized builds and delivers digest-approved images to a registry or node.

Rules for agents: run `piceli help-json` for every command's options, side effects and approval rules; plan before apply and never approve on the owner's behalf; parse JSON from stdout (human text is on stderr); on exit code 2 read `reason` and run `piceli explain <reason> --json`; never read or print secret values; never rely on the current kube context. The project is pre-alpha: check each page's maturity label (stable, preview, experimental).

## Start here

- [Using Piceli from an agent](https://docs.pynenc.org/projects/piceli/en/latest/agents.html): safe commands, approvals, output contract, errors, resume, secrets
- [Command reference](https://docs.pynenc.org/projects/piceli/en/latest/reference/cli.html): every command with options and its contract (generated from `piceli help-json`)
- [Error codes](https://docs.pynenc.org/projects/piceli/en/latest/reference/errors.html): every refusal code with cause, fix and whether a retry can succeed (same as `piceli explain`)

## Docs

- [Overview and architecture](https://docs.pynenc.org/projects/piceli/en/latest/overview.html): model, plan, execute, observe; the engine; glossary
- [Getting started](https://docs.pynenc.org/projects/piceli/en/latest/getting_started/index.html): install, describe a typed app, render it and release it
- [Deploy an app from source](https://docs.pynenc.org/projects/piceli/en/latest/deploy.html): `piceli deploy MODULE:ATTR`, one journaled run of build, deliver, plan, apply and checks; `--plan`, `--approve`, `--resume`
- [Releases from a spec](https://docs.pynenc.org/projects/piceli/en/latest/release_cli.html): `piceli release` plan, apply, adopt, roll back, resume; "If plan refuses"
- [Check a release and roll back automatically](https://docs.pynenc.org/projects/piceli/en/latest/checks.html): `[[checks]]` (http, exec, metric, Python), `rollback_on_failed_checks`, `piceli release check`
- [How plans decide what changes](https://docs.pynenc.org/projects/piceli/en/latest/plans_and_diffs.html): no-op vs apply from server dry runs, field-level diffs, `piceli release diff`
- [Connect to managed clusters](https://docs.pynenc.org/projects/piceli/en/latest/managed_clusters.html): GKE, EKS, AKS and OIDC exec credential plugins with `[target] allow_exec`, pinning and refresh
- [Deployment planning](https://docs.pynenc.org/projects/piceli/en/latest/deployment_planning.html): discovery, pure plans, authorized execution and journals (Python API)
- [Containerized builds](https://docs.pynenc.org/projects/piceli/en/latest/containerized_builds.html): `build.toml`, pinned builders, build receipts
- [Source identity](https://docs.pynenc.org/projects/piceli/en/latest/source_identity.html): `piceli inputs record/verify` and source drift
- [Image delivery](https://docs.pynenc.org/projects/piceli/en/latest/node_delivery.html): `piceli artifacts deliver` to a registry (default) or a node
- [Node-local registry](https://docs.pynenc.org/projects/piceli/en/latest/node_local_registry.html): a registry one node pulls from without configuration
- [Reach your services from your laptop](https://docs.pynenc.org/projects/piceli/en/latest/access.html): declare `app.access.forward`, then `piceli status` (is it up, which URLs) and `piceli access` (supervised port forwards, port-conflict owners)
- [From kubectl scripts to Piceli](https://docs.pynenc.org/projects/piceli/en/latest/migrate_from_kubectl.html): `piceli import live|yaml` generates a typed module from existing objects; adopt it with `--adopt-all-desired`
- [Test against a fake Kubernetes API](https://docs.pynenc.org/projects/piceli/en/latest/testing.html): `piceli.testing` for consumers' own tests, no cluster needed
- [Operations lens](https://docs.pynenc.org/projects/piceli/en/latest/operations_lens.html): `piceli observe`, local UI, logs and port forwards
- [Roadmap and feature status](https://docs.pynenc.org/projects/piceli/en/latest/roadmap.html): maturity of every feature

## Optional

- [Kubernetes model](https://docs.pynenc.org/projects/piceli/en/latest/kubernetes_model/index.html): templates, client models and YAML/JSON definitions
- [Operator workflow](https://docs.pynenc.org/projects/piceli/en/latest/operator_workflow.html): experimental inventory, catalog, approvals and backups
- [Contributing](https://github.com/pynenc/piceli/blob/main/AGENTS.md): how to work on Piceli itself (setup, tests, invariants)
- [Changelog](https://docs.pynenc.org/projects/piceli/en/latest/changelog.html)
