# Overview

# Podplane CLI

## Terminology

- **Components** are platform-level services managed via `install` / `uninstall`. Components are either __core__ components (always installed, cannot be removed e.g. CoreDNS, Cilium) or __addon__ components (can be installed and uninstalled e.g. Envoy Gateway, metrics-server).
- **Apps** are your own workloads, deployed and removed via `deploy` / `remove` using app __templates__ (e.g. `web` or `worker` template).
- Both templates and components can have configurable __features__.

## Command Groups

The Podplane CLI can be divided into groups of commands:

- `cluster` for managing Podplane clusters
- `oidc` for managing Truster deployments
- authentication commands
- `hooks` for integration e.g. kubectl exec auth plugin, podplane TF providers for Netsy state initialization
- app commands for deploying and removing apps using templates
- component commands for managing addon components
- `local` for managing local VM clusters
- `deps` for managing local VM dependency packages
- informational commands

Each CLI command group is summarised below.

## Config Files & Context

Podplane commands use different config/context sources depending on the command:

- __Cluster Config__
  Flags: `-f` / `--cluster-config`, default `./podplane.cluster.jsonc`
  For Commands: `cluster create`, `cluster upgrade`, `cluster delete`, `login`

- __OIDC Server Config__
  Flags: `-f` / `--oidc-config`, default `./podplane.oidc.jsonc`
  For Commands: `oidc *`

- __Kubernetes Context__ 
  Flags: `--context` / `--kubeconfig`, default `kubectl config current-context`
  For Commands: `deploy`, `remove`, `logs`, `install`, `uninstall`, `logout`, `cluster sleep`.
  Exceptions:
  - `logout` optionally also accepts `--cluster` or `-f` / `--cluster-config`
  - `install podplane-operator` also reads `-f` / `--cluster-config` to validate the workload certificate trust domain and CA-key provider

- __No Context/Not Applicable__
  For Commands: `local *`, `deps *`, `version`, `completion`, `help`
  Exceptions:
  - `deps download` optionally accepts `--cluster-config` for auto-detecting providers
  - `local *` commands use `--id` to select the local cluster, defaulting to `default`

The CLI uses the current working directory to find the relevant `podplane.cluster.jsonc` or `podplane.oidc.jsonc` config file. See [Configuration](../configuration.md) for the full file format documentation.

- Alternatively, you can specify a config file path using the `-f` flag e.g. `podplane login -f ./my-cluster/podplane.cluster.jsonc`

`podplane login` also caches a cluster summary used by later kube-context commands. For example, `podplane deploy` uses the cached summary to know whether the selected cluster has a registry mirror. If deploy reports a missing cluster summary, run `podplane login -f <podplane.cluster.jsonc>` for that cluster.

We recommend setting up a Git repository for storing all of your cluster and OIDC server infrastructure-as-code, for example:

```
├── infra/                                        # git repo
│   │
│   ├── auth-production/                          # example Truster server
│   │   ├── podplane.oidc.jsonc                   # config file
│   │   ├── podplane.oidc.schema.json             # generated local editor schema
│   │   └── podplane.*.tf                         # generated .tf files
│   │
│   └── internaltools-production/                 # example cluster
│       ├── podplane.cluster.jsonc                # config file
│       ├── podplane.cluster.schema.json          # generated local editor schema
│       ├── podplane.*.tf                         # generated .tf files
│       └── custom.tf                             # optional custom infrastructure
```

## CLI Storage

Podplane also stores CLI-owned files outside your project directories. These
files are separate from project configuration files such as
`podplane.cluster.jsonc` and `podplane.oidc.jsonc`.

Podplane classifies CLI-owned storage into XDG-aligned categories:

- **Config**: long-term config/auth metadata; meaningful to back up.
- **Cache**: downloaded or derived files that are safe to delete.
- **Data**: durable local VM / local-cluster files.
- **Runtime**: ephemeral process metadata; recreated by restarting Podplane processes.

See [CLI Storage](storage.md) for more details about these files and how they are stored.

## Commands Summary

### `cluster` commands

- `create` generates or reads a cluster config file, generates infra-as-code files, and (for AWS/Google Cloud) deploys the cluster via OpenTofu/Terraform
- `upgrade` downloads newer compatible infrastructure dependencies for a cluster, regenerates its managed files, and optionally applies the upgrade
- `delete` removes deployed infrastructure and leaves config and generated `.tf` files in place.

### `oidc` commands

- `create` generates or reads a Truster config file, generates infra-as-code files, and deploys it to AWS via OpenTofu/Terraform
- `delete` removes deployed infrastructure and leaves config and generated `.tf` files in place.

### authentication commands

- `login` for authenticating via kubectl using the auth URL specified in the cluster configuration file
- `logout` to remove the previously authenticated cluster from your kubeconfig via kubectl

### `hooks` commands

- `kubectl-auth` to be used as a kubectl exec auth plugin

### app commands

These commands help you deploy workloads using templates such as the `web` or `worker` app template.

- `build [PATH] [-t <image>]` builds an OCI image with ocimage and stores it in the local Podplane registry so a local VM can use it immediately. If no `Containerfile` or `Dockerfile` exists, Podplane can generate a conservative `Containerfile` for supported project types.
- `push <local-image> [<remote-image>]` pushes an image from the local Podplane registry to the current cluster registry. If the image is not cached but exists in Docker, Podplane can import and push it after confirmation.
- `deploy <template> --name <name> [--image <image>] [-e KEY=value] [--secret <key>]` deploy an app using a template. The CLI will prompt to install addon components if they have required dependencies which are not installed. Repeat `-e` / `--env` for non-secret environment variables and `--secret` for keys from the cluster's default secrets provider. If `--image` is omitted, the template default image is used.
- `remove --name <name>` remove a previously deployed app.
- `secret <command> --for <secret-provider-class-name>` create, update, list, archive, restore, and destroy application secret values through the Podplane operator. Values are encrypted locally before they are sent to Kubernetes.
- `logs <name>` tail logs for a deployed app, selecting one container or using `--all` for every container.
- `shell <name> [-- command...]` open a shell in a deployed app or run one command in the app container.

The `build` command packages prebuilt files into OCI images without requiring Docker. The `deploy` and `remove` commands are convenience functions which wrap `helm` commands. The `logs` command wraps `kubectl logs`; the `shell` command wraps `kubectl exec` and can fall back to `kubectl debug` or a small client-side prompt when an interactive container has no `bash` or `sh`.

### `install` / `uninstall` commands

Addon components extend your cluster's capabilities, such as Envoy Gateway or CSI drivers.

- `install <component>` installs a component into the cluster with an opinionated, tested configuration.
- `uninstall <component>` removes a previously installed component from the cluster.

These components are installed and managed by Flux CD.

### `local` commands

You can run multiple single-node cluster VMs. Use `--id` to select a cluster; when omitted, `default` is used.

- `start` start a local cluster VM, and creates it if it doesn't exist
- `status` report the status of a local cluster VM
- `stop` stop a local cluster VM
- `delete` delete a local cluster VM and its state files

The following commands exist primarily for Podplane development work on the `vmconfig` package:

- `shell [command]` open a shell into the local cluster VM or run a command via SSH
- `console` attach to the local cluster VM serial console for boot/login debugging; press `Ctrl-]` to detach
- `sync [from] [to]` rsync files into the local cluster VM

The following command exists primarily for debugging:

- `server` runs the shared local background services: cached dependencies and component Git repositories, cloud-init data, fake OIDC, S3, Vault/OpenBao, and Nstance services, plus the host-facing ingress TLS proxy

Note `server` is run automatically in the background when `local start` is used. The current `local stop` implementation stops the shared server whenever it stops a VM; it does not yet preserve the server for another running local VM.

### `deps` commands

The `local` commands automatically download and cache dependencies. These commands exist primarily for debugging that cache.

- `status` reports current state of the cache and if any new dependency versions are available to download
- `download` force-downloads the latest dependency versions
- `tf [--platform OS_ARCH]...` downloads cluster providers and modules for offline use

### informational commands

- `version` reports the current CLI version