The Diploi CLI

Every Diploi development environment comes with the diploi command (short: dip). It works on the deployment you are in: what is running, how it is configured, and what the logs and Kubernetes events say. It also runs commands in your containers, restarts them, and applies the changes you made to diploi.yaml.

Your editor and terminal run in their own container, the development environment, which is separate from the containers your components run in. Both see the same code in /app, so a file you edit here is the file they run. Use diploi exec when something has to run inside a component’s container, with its runtime and its environment. diploi only works from the development environment.

diploi status          # is everything running?
diploi describe        # what is in this deployment, and what is in my environment?
diploi logs api        # what is my component saying?

Note

Run diploi with no arguments to see the commands. diploi help <command> and diploi <command> --help show the options and examples of one command.

Naming things

Most commands take a component: the identifier of a component or add-on in diploi.yaml, such as api, postgres or supabase. That is all you normally need. The CLI picks the running pod and the component’s main container for you, and tells you which one it picked when there is more than one.

Some components run several workloads. Supabase, for example, runs a dozen. Name one after the component to pick it: diploi logs supabase db reads the db pod. A full pod name works too. Name a container after the pod, as in diploi logs supabase db postgres, or use -c <container> to pick one without naming a pod.

Commands

Command	What it does
diploi status	Components, pods, addresses and anything that needs attention
diploi describe [component]	Configuration: paths, addresses, environment variables and where they come from
diploi logs <component>	Recent logs of a component, or a live stream
diploi events [component]	Kubernetes events: why a pod restarted or failed to start
diploi exec <component>	A shell, or one command, inside a container
diploi restart <component>	Restart a component and wait for the new pod
diploi apply	Apply the pending diploi.yaml changes
diploi components [query]	Components and add-ons you can add, with their versions and diploi.yaml entry
diploi agents init	Connect your AI clients to this deployment through the Diploi MCP server

Every command also accepts --json, which prints the same information as JSON instead of text. That is useful in scripts and for AI agents working in the environment. Streaming commands print one JSON object per line.

diploi status

The state of the whole deployment:

• Every component with its state (ok, starting, problem or no pods), public url and internal addresses
• Its pods with phase, readiness, restarts and age
• The diploi.yaml changes that are not applied yet, with a heads-up when applying them needs care (see Adding a component)
• A Problems list in plain words, such as a container stuck in CrashLoopBackOff, an image that cannot be pulled, or a configuration error

A deployment that is only starting up is not a problem, so an empty list means there is nothing to look into.

diploi status
diploi status --json

diploi describe

What the deployment is configured with. This is the applied configuration, not the file on disk.

Without a component it describes the deployment: its components and the folder each one lives in, the environment variables available in your development environment, and the init commands. Every variable is listed with the component it came from.

diploi describe

With a component it describes that component:

• The folder of its code, its main container and the commands it starts with
• Its image, volumes, public url and internal addresses
• Its parameters and connection strings
• Every environment variable with its origin: a parameter from the Setup tab, a value from the Environment tab, a static value in diploi.yaml, a default from the package, an import from another component, the component’s own address, or a built-in Diploi variable such as DIPLOI_NAMESPACE

diploi describe postgres
diploi describe postgres --reveal   # with the secret values

Secret values are masked unless you pass --reveal.

diploi logs

The last 200 lines of a component’s log, or a live stream with --follow. diploi log works too.

diploi logs api
diploi logs api --follow
diploi logs api --since 10m           # a time window instead of a line count
diploi logs api --previous            # the log of the container that crashed
diploi logs api --all-containers      # including init and sidecar containers

Option
-f, --follow	Stream new lines as they arrive
-n, --lines <number>	Lines to show, 0 for all (default 200, or all with --since)
--since <duration>	Only newer than e.g. 30s, 10m, 2h, 1d
--since-time <timestamp>	Only after an RFC3339 timestamp
--timestamps	A timestamp on every line
-p, --previous	The previously terminated container instance
--all-containers	Every container of the pod, each line tagged
-c, --container <name>	A specific container
-q, --quiet	Do not print which pod was picked

diploi events

The Kubernetes events of the deployment, oldest first: pods being scheduled and started, images pulled, probes failing, containers backing off. Look here when a pod never reaches a running state and its log is empty.

diploi events                  # the newest 100 events
diploi events api --since 10m
diploi events -w               # only warnings
diploi events -n 20            # only the newest 20

diploi exec

Runs something inside a component’s container. Without a command it opens an interactive shell. With a command after -- it runs that one command and returns its exit code.

diploi exec api                              # a shell in the api container
diploi exec api -- npm install lodash        # install a dependency where it runs
diploi exec api -- npm run migrate
diploi exec api -- sh -c 'npm run build && npm start'
cat dump.sql | diploi exec postgres -- psql -U postgres

The command runs as it is, without a shell. For pipes, && or the container’s own variables, wrap it in sh -c '…' as above. The single quotes also keep your own terminal from expanding anything first.

-u 1000:1000 runs as another user, and -t forces a TTY for commands that expect one. --no-tty turns the TTY off, and --no-stdin does not pass your input to the command.

Tip

Code dependencies, like npm or pip packages, are installed when the pod starts. You can also install them yourself, either with diploi exec or in the component’s folder from your own terminal, because both see the same files in /app.

A system package is different. One installed with diploi exec is gone when the component restarts, so add it to the component’s Dockerfile and Dockerfile.dev instead. For a tool you only need in your own terminal, use development.initCommands.

diploi restart

Restarts a component by deleting its pod, and the deployment immediately creates a new one. The command waits until the new pod is running and ready, so it is finished when the component is back. It waits up to 2 minutes, and exits with code 2 when no new pod becomes ready in that time.

diploi restart api
diploi restart supabase db         # one workload of a multi-workload component
diploi restart supabase --all      # every pod of the component
diploi restart api --timeout 300   # wait up to 5 minutes (at most 600 seconds)
diploi restart api --no-wait

diploi apply

Applies the changes you made to diploi.yaml, such as added or removed components and add-ons, changed environment imports and changed versions. This is what the Apply changes button in the Console does.

diploi status shows what is pending before you apply. A change to diploi.yaml takes a few seconds to be checked, and diploi apply right after saving waits for that first, so it always applies the file as it is. It then waits until every new and changed component is deployed and ready, and lists each one with its state, folder and public url. Removed components are waited for too, until their pods are gone. When a component fails, for example because its container keeps crashing, or is not ready before the timeout, the command says so and exits with code 2.

diploi status              # "Pending changes" lists what would be applied
diploi apply               # wait for the changed components, up to 5 minutes
diploi apply --timeout 600
diploi apply --no-wait     # return right after applying

Applying acts as the user assigned to the deployment in the Console (under Git), or as the user who created the deployment when the project has no repository.

Adding a component

When you add a component to diploi.yaml, applying creates its folder (/app/<identifier>, or its folder) from the component’s starter: its Dockerfile and Dockerfile.dev, its configuration and its starter code. This only happens when the folder does not exist yet, so add the component and apply first, then build on the starter.

If the folder already exists, for example because you are adding a component for code you already have, it is left as it is and the component gets none of the starter files. Both diploi status and diploi apply point this out. Staging and production builds need the Dockerfile, so add it yourself in that case.

Note

Changing the environment variables or the development.initCommands of the development environment restarts it when you apply: running processes stop, and tools installed outside /app and the home folder have to be installed again. diploi apply answers right away in that case, without waiting for the components.

diploi components

The components and add-ons you can add to diploi.yaml: the same list the Console offers, with the versions that exist. With a query (an identifier, a name or a few words) it shows the matches in detail: every version, the environment variables other components can import from it, the add-ons it needs, and the entry to paste into diploi.yaml.

diploi components             # everything that can be added
diploi components next        # versions and the diploi.yaml entry of Next.js
diploi components react ssr   # everything matching "react ssr"

Use one of the listed versions: a version that does not exist makes diploi.yaml fail to apply, and diploi status then lists the versions that do. The entry includes the add-ons a component needs, such as the database of Odoo; leave out the ones your diploi.yaml already has.

diploi agents

Sets up the AI clients you bring along, so they can use the tools of this deployment. Claude Code, Codex and Gemini CLI get the Diploi MCP server and are pointed at the instructions in /etc/diploi/AGENTS.md. VS Code gets the MCP server only. Cursor is only configured with --project, which writes AGENTS.md and .cursor/mcp.json into the project. Your existing settings are kept, and only what is missing is added.

OpenCode and Continue come with the development environment and Diploi configures them itself (see Built-in tools), so they need nothing from you.

diploi agents init             # configure the clients that are not configured yet
diploi agents init --project   # also write AGENTS.md and .cursor/mcp.json into the project
diploi agents init --force     # configure every client again, also the ones you changed

This already runs when the development environment starts, and each client is configured only once, so a file you delete or change is not touched again. Run it yourself with --force to restore files you deleted or changed, or with --project to add the project files.

See also

• Using Remote Development
• diploi.yaml Explained
• Troubleshooting