CLI overview
The erun CLI is ERun's automation surface. It's what CI/CD pipelines invoke for build / push / deploy, what runs inside every runtime pod, and what the desktop app shells out to when you click a button. If you're scripting, running on a build runner, or working headlessly, the CLI is your interface.
erun init
Initialize ERun configuration for a tenant and environment. On a local environment, init creates the per-user tenant/env files and prepares the local Kubernetes context. On a remote environment, it deploys the runtime pod — straight from the published erun-devops chart — and writes the in-pod bootstrap marker. init does not generate any files into your project beyond .erun/config.yaml; the runtime chart and image ship as release artifacts, and projects that need a custom toolchain extend the published image instead (see --runtime-image below).
erun open
Open a shell in the tenant environment. open is a pure primitive builds-here envs build → push → deploy, runtime envs install the current version). The desktop app composes build → push → deploy itself and opens the pure shell.
erun stop
Stop an environment's runtime so the capacity it was holding goes back to the environments you are actually using. Opening the environment again starts it.
erun delete
Delete an environment from your ERun configuration and remove its remote runtime namespace.
erun build
Build the project's container image(s). erun build runs only in agent envs — runtime envs receive deploys of already-built artifacts. See Environment types.
erun pin
Re-pin every place an environment records its erun version — in one motion.
erun release
Mark a project release in source control. erun release is repository-wide: it moves all modules together — erun-cli, erun-common, erun-mcp, erun-ui, and erun-devops — and commits and tags them as one version.
erun push
Publish a version's outputs to the configured container registry: the multi-arch image manifests and their helm charts. erun push --version is the publish step of the delivery pipeline — it takes a version erun build minted and makes it deployable.
erun deploy
Install a published version into a Kubernetes environment. erun deploy is a pure consume step — it helm-installs the image and chart that erun push already published at a version, addressing them by reference. It never builds, pushes, or publishes. It's the deploy step of the delivery pipeline; see Command primitives for how it composes with build and push.
erun e2e
Discover the project's playwright/ folder the way erun build discovers docker/ and erun deploy discovers k8s/, then run it once against a real, already-deployed environment. See Delivery pipeline · What e2e does for where this sits in the flow.
erun publish
Mirror an already-built version's images from the from registry to each to registry, without building or deploying. erun publish --version is a pure primitive: use it to hand a version you have iterated on and tested — for example one built against a local cluster registry — to other users, by copying that exact multi-arch image to a shared registry such as ghcr.io/.
erun expose
Expose an in-namespace Service at a stable public hostname under the platform's services zone. erun expose is for platform deployments — installations that run the PowerDNS singleton and declare a platform it ensures a per-environment wildcard DNS record points at the env's ingress IP, and it applies a Host-routing Ingress for the Service.
erun terraform
Run a hosted platform's per-environment Terraform without hand-running terraform or cd-ing into a folder. erun terraform is for platform deployments whose Terraform is laid out per environment — one folder per env under terraform-/, scaffolded by the erun-blueprint-platform skill. erun resolves the env's root from the current scope — terraform-// at the project root, or -devops/terraform-// when the tenant keeps its whole devops footprint (docker/, k8s/, terraform-/) under -devops/ (the same -devops convention build/deploy use) — picks up the symlinked common.tf, and runs that env's own main.tf with its .tfvars. The terraform- base is the default; relocate it with paths.terraform in .erun/config.yaml (erun still appends /).
erun upgrade
Redeploy every environment opted into Upgrade all to the latest version for its release channel. erun upgrade is the one-command way to roll a fleet of environments forward without running erun deploy for each — it resolves the latest version per channel, then redeploys only the environments whose current version lags. It is an orchestrator over erun deploy --version: it never builds or pushes, it resolves a version per environment and installs it by reference. The versions it picks were minted by build and published by push (or by a release) ahead of time.
erun cloud
Set up and manage cloud provider aliases — the cloud credentials that managed cloud contexts and remote environments use. AWS aliases carry an IAM Identity Center profile and the OIDC issuer the deployed ERun APIs trust; Cloudflare aliases carry a delegated, account-scoped API token. An AWS alias is named +@aws; a Cloudflare alias is named +@cloudflare. Aliases are stored in your root ERun config — except the Cloudflare token itself, which is held in a local secret store referenced from config (never written into erun-config.yaml).
erun context
Create and power managed cloud contexts. A managed cloud context is an EC2 instance running k3s that ERun provisions for you — environments deploy into it. It bills while running, so the lifecycle is: create once, then start and stop around your working day.
erun platform
Talk to a hosted erun platform's own control-plane API (erun-backend-api) directly — the same API the hosted console drives — using the erun-type cloud alias erun cloud init erun and erun cloud login set up. It exists so an Operator or Agent can exercise or smoke-test a deployed control plane without a browser-obtained token: registering tenants and users, listing and managing hosted environments, bootstrapping or reusing cloud contexts, and previewing a full provisioning plan before running it.
erun review
Review code on a hosted erun platform from a terminal or an Agent — the client for the collaboration API — using the erun-type cloud alias erun cloud init erun and erun cloud login set up. List reviews, open one, comment on a line (or reply to an existing comment), resolve or reopen a comment thread, record a build against a review (or report one MERGED once its promoted environment has gate-built and pushed it), close a review, requeue one stuck at MERGE, assign or remove reviewers, and inspect or advance a target branch's merge queue.
erun gate
The queue view merge queue § Watching the gate asks for list and show. Reporting a gate run's start and outcome is erun exec gate-run, not here — this is the read side.
erun jobs
The platform's record of work in flight: what agents and orchestrators are working on right now, and what recently finished. Builds and gate runs are reported after the work completes; a job is claimed before it starts, which is the half that lets two actors see each other and stop duplicating work.
erun sshd
Enable SSH access to a remote environment — the prerequisite for attaching an IDE (erun open --vscode / --intellij) or connecting over plain SSH.
erun list
List all configured tenants and environments, the effective target for the current directory, and configured cloud providers. list is read-only and never mutates state. (To list managed cloud contexts, use erun context list.)
erun outputs
List and download the files an agent (Claude/Codex) produced inside an environment's runtime pod. This is the inverse of pasting a file into the pod from the desktop terminal — erun outputs pulls deliverables out.
erun inputs
Place a file from this machine inside an environment's runtime pod. This is the inverse of erun outputs — outputs pulls deliverables out of the pod, inputs pushes a file in.
erun idle
Show an environment's idle and auto-stop status. Read-only — it reports what the idle monitor sees and would do, and records no activity itself (so checking status never keeps an environment alive).
erun whip
Push every live orchestrator and environment agent to keep moving, on demand, and report exactly who was pushed and who was skipped — and why.
erun observe
Report an environment's Kubernetes state. Read-only — every call it makes is a kubectl get, never anything that can create, change, or delete a cluster object, which is what makes it safe to grant to an orchestrator that must never be handed erun exec raw.
erun services
List the Services an environment's namespace runs, with each one's type, ports, and the public address it already has. Read-only — both reads are kubectl gets, never anything that can create, change, or delete a cluster object, which is what makes it safe to grant to an orchestrator that must never be handed erun exec raw.
erun orchestrator
Manage host-side AI orchestrator definitions from the terminal — the config-file counterpart to the desktop's Edit orchestrator dialog (see Desktop app · Orchestrators), so config.yaml is not the only way to change one.
erun usage
Report an environment's live CPU, memory, and disk usage, read straight from the runtime container's own cgroup accounting — no cluster metrics add-on needed, so it works even where kubectl top reports itself unavailable (every local orbstack/k3s-style cluster included).
erun resize
Change the runtime pod's and/or the erun-dind sidecar's CPU/memory limits and roll them out — without re-running erun init to change these numbers.
erun doctor
Inspect the local ERun configuration or the runtime pod state, report why a deploy may have failed, and offer recovery actions for any problems it finds.
erun version
Print the CLI's build version and commit.
erun mcp
Run ERun as a Model Context Protocol (MCP) server over HTTP. This is the entry point used by IDEs, Agents, and the desktop app's port-forward to the in-pod MCP container.
erun api
Run ERun's backend API server over HTTP. This is an infrastructure command — it's wired into the hosted backend deployment, not something you run day to day. It launches the eapi binary; the CLI itself doesn't host the API.
erun app
Launch the ERun desktop app. Starts the app detached and returns immediately, so you can launch it from a terminal without tying up the shell.
erun exec
Repository helpers that run from the project root. Fourteen subcommands: diff (a structured git diff), raw (run an arbitrary command), write (write file content), commit (commit every change), push (push a branch to a remote), merge (merge a branch into the current one), gate-merge (build the prospective squash merge a merge queue promotion gates), report-commit-status (report a GitHub commit status for a merge queue gate result), close-pr (close the GitHub pull request a merge queue gate actually shipped), gate-run start/gate-run report (make one gate attempt visible on erun gate list, independent of whether an erun review exists for the change), reconcile-bypass (check every ruleset-bypassed push against a real passed gate run), plan-ruleset-bypass (plan narrowing a ruleset's bypass grant to one non-human queue identity), and route-check (prove every registered API route is reachable on a deployed plane).
erun contribute
Contribute-mode helpers for working on ERun itself from inside an environment.