Shell Access

Open an interactive terminal session inside a running service container from the CLI.

edge service shell connects your local terminal directly to a running container over a secure WebSocket. The session behaves like a normal SSH shell — you get a full PTY with colour output, tab completion, and automatic resize when you resize your terminal window.

Usage

edge service shell <svc-slug>

Global flags

All standard global flags apply — --workspace, --project, --env, --token, --api-url. If you have already run edge link in your project directory, the workspace/project/env context is picked up automatically.

Requirements

Requirement	Detail
Service type	`docker` only — managed databases do not expose a shell endpoint
Service status	Must be `running` — stopped or deploying services will return an error
Auth	JWT token or project token (`sk_proj_*`)

Examples

# Shell into "api" in the currently linked environment
edge service shell api

# Explicitly target an environment
edge service shell api -w acme -p backend -e production

# Works with project tokens too (e.g. in a restricted bastion)
CLOUD_TOKEN=sk_proj_... edge service shell api

How it works

The CLI resolves your workspace/project/environment context and looks up the service slug.
A WebSocket connection is opened to the API at wss://api.cloud.simplifyd.com/v1/workspaces/:ws/projects/:p/envs/:e/svcs/:slug/shell. Your auth token is passed as a query parameter (?jwt=…), which is required because browsers and WebSocket clients cannot set custom headers during the HTTP upgrade.
Your terminal is put into raw mode so every keystroke is forwarded to the container unmodified — including arrow keys, Ctrl+C, Tab, and other control sequences.
The container shell is /bin/bash, falling back to /bin/sh if Bash is not installed.
When you resize your terminal window, the CLI sends a resize event to the server, which updates the PTY dimensions so full-width output (like htop or vim) reflows correctly.
The session ends when you type exit, press Ctrl+D, or interrupt with Ctrl+C.

Multi-replica deployments

In environments with multiple replicas, the platform routes your shell connection to one replica — there is no guarantee which one. If you need to reach a specific replica (e.g. to inspect local state), check the pod name with kubectl or use the service's log output to identify the instance.

Non-interactive use

If stdin is not a TTY (e.g. you are piping input), the CLI skips raw mode and PTY resize but still establishes the WebSocket connection. This lets you pipe commands into a container:

echo "ls -la /app" | edge service shell api

Non-interactive use is best-effort. Complex interactive programs (vim, htop, psql) require a real TTY and will not render correctly when piped.