> ## Documentation Index
> Fetch the complete documentation index at: https://qovery-docs-agent-console-2026-09-29.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
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:

```bash theme={null}
qovery shell
```

### Shell with explicit flags

```bash theme={null}
qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api"
```

### Shell into specific pod or container

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
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.

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

#### Debug mode

```bash theme={null}
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.

<Warning>
  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.
</Warning>

#### 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

```bash theme={null}
# 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

```bash theme={null}
qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "npm,run,migrate"
```

### Check Application Files

```bash theme={null}
# 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

```bash theme={null}
qovery shell --ephemeral \
  --memory 4Gi \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --command "python,scripts/backfill.py"
```

### Debug Specific Container

```bash theme={null}
qovery shell \
  --organization "my-org" \
  --project "my-project" \
  --environment "production" \
  --service "my-api" \
  --pod "my-api-7d4f9c-xvz" \
  --container "nginx-proxy"
```

## Tips

<Tip>
  Use interactive shell (run `qovery shell` without flags) for exploratory debugging when you don't know the exact service name.
</Tip>

<Tip>
  You can pass the Qovery Console URL as an argument to `qovery shell` to quickly connect to a service.
</Tip>

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

## Related Commands

* [`qovery log`](/cli/commands/log) - View application logs
* [`qovery application`](/cli/commands/application) - Manage applications