Skip to main content
Execute a command (interactive shell by default) in a running container within a service. If the service has multiple replicas and no container ID is specified, a random container is selected.

​
Usage

uc exec [OPTIONS] SERVICE [COMMAND ARGS...]

​
Arguments

​
SERVICE
string
required
Name or ID of the service.
​
COMMAND
string[]
Command and arguments to execute. Defaults to an interactive shell (bash or sh).

​
Flags

​
--container
string
ID of the container to exec into. Accepts full ID or a unique prefix. If not specified, a random container from the service is selected.
​
-d, --detach
Detached mode - run command in the background.
​
-T, --no-tty
Disable pseudo-TTY allocation. By default uc exec allocates a TTY when connected to a terminal.

​
Examples

​
Start an interactive shell

By default, tries bash first, falls back to sh: 
uc exec web

​
Start a specific shell

uc exec web /bin/zsh

​
Run a command

uc exec web ls -la /var/www

​
Execute in a specific container

Use the full container ID or a unique prefix: 
uc exec --container d792e web ls -la

​
Pipe input to a command

cat backup.sql | uc exec -T db psql -U postgres mydb
The -T flag disables TTY allocation for piping.

​
Run a task in the background

uc exec -d web /scripts/cleanup.sh

​
Run a database query

uc exec db psql -U postgres -c "SELECT * FROM users LIMIT 10"

​
Access a service shell with multiple replicas

If a service has multiple replicas, exec connects to a random one: 
uc exec web
To choose a specific replica, use --container: 
uc ps | grep web
uc exec --container abc123 web

​
Interactive Shell

The default command tries to start the best available shell:
  1. First tries bash
  2. Falls back to sh if bash is not available
This works in most containers: 
uc exec web
Inside the container: 
root@abc123:/app# ls
index.html  static/  config/
root@abc123:/app# exit

​
Detached Mode

Run a command in the background: 
uc exec -d worker python /app/process_data.py
This starts the command and returns immediately. View logs to see output: 
uc logs worker

​
Container Selection

If a service has multiple replicas: 
uc service ls
Output: 
NAME   MODE         REPLICAS   IMAGE
web    replicated   3          nginx:latest
Without --container, exec picks a random replica: 
uc exec web hostname
With --container, target a specific one: 
uc ps | grep web
uc exec --container abc123 web hostname

​
Common Use Cases

​
Debug application issues

uc exec web cat /var/log/app.log

​
Check running processes

uc exec web ps aux

​
Test database connection

uc exec api nc -zv db 5432

​
Run database migrations

uc exec api python manage.py migrate

​
Access Rails console

uc exec web rails console

​
Access Django shell

uc exec api python manage.py shell

​
Import data into database

cat data.sql | uc exec -T db psql -U postgres myapp

​
Check environment variables

uc exec web env

​
TTY Behavior

By default, uc exec allocates a pseudo-TTY when:
  • stdin is a terminal
  • Command is interactive (like a shell)
Disable TTY with -T when:
  • Piping input: cat file | uc exec -T service command
  • Piping output: uc exec -T service command | grep pattern
  • Running in CI/CD pipelines

​
Exit Codes

When running in attached mode (default), uc exec exits with the same code as the executed command: 
uc exec web false
echo $?
# Output: 1

uc exec web true
echo $?
# Output: 0

Build docs developers (and LLMs) love

Get started for freeTalk to us