Screen Basics

runnem uses GNU screen to manage your services. Understanding screen basics will help you get the most out of runnem.

What is Screen?

GNU screen is a terminal multiplexer that allows you to:

• Run multiple terminal sessions in a single window
• Detach from sessions and reattach later
• Share sessions between users
• Keep processes running even when disconnected

Screen Commands

Basic Navigation

• Ctrl+A then D - Detach from current screen session
• Ctrl+A then C - Create a new window
• Ctrl+A then N - Next window
• Ctrl+A then P - Previous window
• Ctrl+A then 0-9 - Switch to window number
• Ctrl+A then " - List all windows

Session Management

• screen -ls - List all screen sessions
• screen -r - Reattach to last detached session
• screen -r <session> - Reattach to specific session
• screen -X quit - Quit a screen session

How Runnem Uses Screen

runnem creates a screen session for each service:

# When you run
runnem up api

# runnem creates a screen session like
screen -S runnem-api -dm bash -c "cd ~/projects/myapp/api && npm run dev"

Viewing Logs

When you run runnem log api, runnem:

1. Finds the screen session for the service
2. Attaches to it to show the logs
3. You can detach with Ctrl+A then D

Multiple Services

Each service runs in its own screen session:

# List all screen sessions
screen -ls

# You might see
runnem-api
runnem-frontend
runnem-database

Best Practices

1. Use Ctrl+A then D to detach from logs
2. Don't manually quit screen sessions (use runnem down)
3. Check screen sessions with screen -ls
4. Use runnem log instead of manual screen commands
5. Let runnem manage screen sessions for you

Troubleshooting

If you encounter screen-related issues:

1. Check for orphaned sessions:

screen -ls

2. Clean up old sessions:

screen -X -S <session> quit

3. Verify runnem can access sessions:

runnem list