qovery shell

Shell access and command execution

Overview

Connect to an application container and execute commands in running service instances, or open an interactive shell session. With --ephemeral, open the shell in a temporary pod or container instead.

Usage

qovery shell [flags]
qovery shell <qovery_console_service_url>

Commands

Interactive Shell (interactive mode)

When run without flags, qovery shell prompts you to select your organization, project, environment, and service interactively:

qovery shell

Shell with explicit flags

qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"

Shell into specific pod or container

qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --pod "pod-name" \
  --container "container-name"

Execute Command

Run a specific command instead of opening an interactive shell:

qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "ls,-la"

The --command flag is a comma-separated string slice and can be repeated to pass multiple arguments.

Shell via Console URL

Pass the Qovery Console URL directly:

qovery shell "https://console.qovery.com/organization/<org-id>/project/<project-id>/environment/<env-id>/application/<app-id>"

Ephemeral Shell

--ephemeral opens the shell in a temporary pod or in a temporary container, instead of the application container. It requires Qovery CLI v1.162.1 or later. Choose where the shell runs with --mode:

Mode	What it does	Use it to
clone (default)	Creates a separate pod from the service image. It receives no traffic.	Run one-off commands or inspect the service configuration without touching the running pods
debug	Adds a debug container to a running pod of the service. That pod keeps serving traffic.	Troubleshoot a running pod, for example an image that has no shell or tools

Clone mode

qovery shell --ephemeral \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"

The new pod uses the same image, environment variables, secrets, volumes, service account, security context and node placement as the service. It runs sleep infinity instead of the service entrypoint, so your application does not start in it and the pod receives no traffic.

The pod gets the same CPU and memory as the service. Use --cpu and --memory to give it more, for example for a heavy script or a data migration. Each flag sets both the request and the limit:

qovery shell --ephemeral --mode clone \
  --memory 2Gi \
  --cpu 1 \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"

The pod is deleted when you exit the shell, and after 24 hours at most. The CLI waits up to 5 minutes for it to start.

Clone mode works for applications and containers without persistent storage. It fails with No deployment found for service on services that use persistent storage.

Debug mode

qovery shell --ephemeral --mode debug \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"

Qovery adds a debian:stable-slim container to the newest running pod of the service. The container shares the process namespace of the application container, so tools like ps and top show the application processes. The CLI waits up to 2 minutes for the container to start. --cpu and --memory do not apply in this mode and are ignored.

Kubernetes cannot remove a debug container from a pod. The container stays in the pod until the pod is replaced, for example by the next deployment. If you open another debug shell on the same pod, Qovery reuses the existing container.

Permissions

Clone mode requires the same permissions as qovery shell. Debug mode requires admin access to the cluster. Both are recorded in the audit logs.

Options

Flag	Shorthand	Description
--organization		Organization Name
--project		Project Name
--environment		Environment Name
--service		Service Name
--pod	-p	Pod name to exec into
--container		Container name inside the pod
--command	-c	Command to launch inside the pod (string slice, default: sh; can be repeated)
--ephemeral		Open the shell in an ephemeral pod or container instead of an existing pod
--mode		Ephemeral mode, used with --ephemeral: clone (default) or debug
--cpu		CPU request and limit of the clone pod, e.g. 500m or 2 (--mode clone only)
--memory		Memory request and limit of the clone pod, e.g. 512Mi or 2Gi (--mode clone only)
--help		Show help

Examples

Debug Application

# Open interactive shell
qovery shell

# With explicit context flags
qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"

Run Database Migrations

qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "npm,run,migrate"

Check Application Files

# List application files
qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "ls,-lah,/app"

Run a Script Without Touching Production Pods

qovery shell --ephemeral \
  --memory 4Gi \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "python,scripts/backfill.py"

Debug Specific Container

qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --pod "my-api-7d4f9c-xvz" \
  --container "nginx-proxy"

Tips

Use interactive shell (run qovery shell without flags) for exploratory debugging when you don’t know the exact service name.

You can pass the Qovery Console URL as an argument to qovery shell to quickly connect to a service.

Be careful when executing commands in production environments. Changes are not persistent across pod restarts.

Related Commands

• qovery log - View application logs
• qovery application - Manage applications