Skip to main content

gws exec

Execute commands in a service container.

Usage​

gws exec <service> -w [worktree] -p [project] [options]
gws exec <service> -- <command> [args...]

Output:

# Interactive shell
root@api-pod:/app#

# Command execution
Database migration completed successfully!

Note: This command can be run from anywhere using the -p [project] option.

Arguments​

  • <service> - Name of the service to execute command in. Required.
  • [command...] - Command and arguments to execute (optional, defaults to /bin/sh)

Options​

OptionDescriptionDefault
-w, --worktree <name>Worktree nameMain project deployment
-p, --project <name>Project nameAuto-detected from current directory
-i, --stdinPass stdin to the containerAuto (true for shell)
-t, --ttyAllocate a TTYAuto (true for shell)
-c, --container <name>Container name (for multi-container pods)First container
--shell <path>Shell to use for interactive mode/bin/sh

Examples:

# Open interactive shell (default worktree)
gws exec api

# Open shell in specific worktree
gws exec api -w feature-auth

# Run specific command
gws exec api -- npm run migrate

# Execute database query
gws exec database -- psql -U postgres -c "SELECT * FROM users;"

# Check container environment
gws exec api -- env

# Inspect files
gws exec api -- ls -la /app

# Use bash instead of sh
gws exec api --shell /bin/bash

# Target specific container in multi-container pod
gws exec api -c sidecar-container -- ls /data

Typical Use Cases​

Debug application​

# Open shell to inspect application state
gws exec api -w feature-auth

# Inside container:
cd /app
cat .env
ps aux

Run database migrations​

# Execute migration script
gws exec api -w feature-auth -- npm run migrate:latest

Clear cache​

# Clear Redis cache
gws exec redis -w feature-auth -- redis-cli FLUSHALL

Check logs in container​

# View application logs
gws exec api -w feature-auth -- tail -f /var/log/app.log

Multirepo Behavior​

When running gws exec in a multirepo setup, the command targets a specific service within the shared namespace.

Project Structure​

myapp/                          # Parent directory
├── .worktrees/                 # Shared worktrees folder (at parent level)
│   └── feature-auth/           # One folder per worktree name
│       ├── api/                # Worktree for api repo
│       │   └── src/
│       └── app/                # Worktree for app repo
│           └── src/
├── api/                        # Git repo 1
│   ├── .git/
│   └── src/
└── app/                        # Git repo 2
    ├── .git/
    └── src/

Executing in Main Workspace​

cd myapp
gws exec api -- npm run migrate

What happens:

  • Finds the api service pod in namespace myapp
  • Executes the migration command inside the api container

Executing in Worktree​

cd myapp
gws exec api -w feature-auth -- npm run migrate

What happens:

  • Finds the api service pod in namespace myapp-feature-auth
  • Executes the migration command inside the worktree's api container

Key Points:

  • All services (api, app, database) are deployed to the same namespace
  • You specify which service to execute commands in
  • The worktree flag determines which namespace (deployment) to target
  • Each service runs in its own pod but shares the namespace

Understanding exec​

The exec command uses kubectl exec under the hood to access the container. It:

  1. Identifies the pod for the service
  2. Connects to the running container
  3. Executes the specified command
  4. Returns the output

Security Considerations​

  • Commands run with the same user as the container process
  • File changes persist only until the pod restarts
  • Be careful with destructive commands
  • Use for debugging and diagnostics, not for production changes

See Also​