qovery shell

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.

qovery log - View application logs
qovery application - Manage applications

Getting Started

Commands

Troubleshooting

Overview

Usage

Commands

Interactive Shell (interactive mode)

Shell with explicit flags

Shell into specific pod or container

Execute Command

Shell via Console URL

Ephemeral Shell

Clone mode

Debug mode

Permissions

Options

Examples

Debug Application

Run Database Migrations

Check Application Files

Run a Script Without Touching Production Pods

Debug Specific Container

Tips

​Overview

​Usage

​Commands

​Interactive Shell (interactive mode)

​Shell with explicit flags

​Shell into specific pod or container

​Execute Command

​Shell via Console URL

​Ephemeral Shell

​Clone mode

​Debug mode

​Permissions

​Options

​Examples

​Debug Application

​Run Database Migrations

​Check Application Files

​Run a Script Without Touching Production Pods

​Debug Specific Container

​Tips

​Related Commands

Overview

Usage

Commands

Interactive Shell (interactive mode)

Shell with explicit flags

Shell into specific pod or container

Execute Command

Shell via Console URL

Ephemeral Shell

Clone mode

Debug mode

Permissions

Options

Examples

Debug Application

Run Database Migrations

Check Application Files

Run a Script Without Touching Production Pods

Debug Specific Container

Tips

Related Commands