Workflow: Running Commands

Overview

This guide walks you through the complete workflow of running shell commands in Shell App, from creating a session to executing commands and managing output.

Time Required: ~2-5 minutes for setup, then continuous use Skill Level: Beginner to Intermediate

Prerequisites

Before starting this workflow, ensure:

• Shell App is accessible (via app launcher or bottom panel)
• Shell server is running and connected (green status indicator)
• You have appropriate permissions for the commands you intend to run

Steps

Step 1: Create or Select a Terminal Session

You need an active terminal session to run commands.

To create a new session:

1. Click the New Terminal button in the sidebar, or press Ctrl+Shift+` (Windows/Linux) or Cmd+Shift+` (macOS)
2. Enter a descriptive Display Name (e.g., "Build Commands", "Server Logs")
3. Optionally select context (Workspace, Project, Milestone, Task)
4. Click Connect

To use an existing session:

1. Click on a session name in the sidebar
2. The terminal view switches to that session
3. If the session was disconnected, it will automatically reconnect

Step 2: Navigate to Your Working Directory

Once connected, navigate to the directory where you want to work:

# Check your current location
pwd

# Navigate to your project directory
cd /path/to/your/project

# Verify you're in the right place
ls -la

Pro Tip: Create separate sessions for different project directories to avoid repeatedly navigating.

Step 3: Execute Commands

Type your command and press Enter to execute:

# Example: Check Node.js version
node --version

# Example: Install dependencies
npm install

# Example: Run tests
npm test

# Example: Start a development server
npm run dev

The terminal displays output in real-time with full color support.

Step 4: Handle Long-Running Commands

For commands that run continuously (servers, watch processes):

Running in foreground:

# Start dev server (blocks terminal)
npm run dev

• Output streams in real-time
• Use Ctrl+C to stop the process
• Terminal is occupied until process ends

Running in background:

# Start in background
npm run dev &

# Or use nohup for persistence
nohup npm run dev > output.log 2>&1 &

Pro Tip: Create dedicated sessions for long-running processes so you can continue working in other sessions.

Step 5: Manage Command Output

Clear the screen:

• Press Ctrl+K (Windows/Linux) or Cmd+K (macOS)
• Or type clear and press Enter

Scroll through history:

• Use mouse scroll wheel
• Or use Shift+Page Up / Shift+Page Down

Save output to file:

# Redirect output to file
npm test > test-results.txt

# Capture both stdout and stderr
npm build 2>&1 | tee build.log

Step 6: Use Multiple Sessions Efficiently

For complex workflows, use multiple sessions:

Switch between sessions:

1. Click the session name in the sidebar
2. Use keyboard shortcut Ctrl+` / Cmd+` to focus terminal

Step 7: Link Sessions to Tasks (Optional)

For tracking work, associate sessions with FlowState entities:

1. When creating a session, select:

   • Workspace (required)
   • Project (optional, enables milestone selection)
   • Milestone (optional, enables task selection)
   • Task (optional, links terminal to specific work item)

2. Benefits:

   • Organize terminals by project context
   • Track which commands relate to which tasks
   • Filter sessions by context later

Expected Results

After completing this workflow, you should have:

• One or more active terminal sessions
• Commands executing and displaying output correctly
• Understanding of session management for different workflows
• Optionally, sessions linked to project context

Common Command Patterns

Development Workflow

# 1. Pull latest code
git pull origin main

# 2. Install dependencies
npm install

# 3. Start development server
npm run dev

# 4. In another session, run tests
npm test -- --watch

Build and Deploy

# 1. Run linting
npm run lint

# 2. Run tests
npm test

# 3. Build for production
npm run build

# 4. Deploy (example)
npm run deploy

Log Monitoring

# Follow logs
tail -f /var/log/application.log

# Search logs
grep "ERROR" /var/log/application.log

# Watch Docker logs
docker logs -f container-name

Troubleshooting

Issue: Command not found

Solution: Check that the executable is in your PATH:

# Check PATH
echo $PATH

# Find command location
which node

# Add to PATH if needed
export PATH=$PATH:/path/to/bin

Issue: Permission denied

Solution: Check file permissions:

# View permissions
ls -la script.sh

# Make executable
chmod +x script.sh

# Run with sudo (if needed)
sudo command

Issue: Process won't stop

Solution: Force terminate:

1. Press Ctrl+C (standard interrupt)
2. If unresponsive, press Ctrl+\ (SIGQUIT)
3. As last resort, close the session

Issue: Terminal output garbled

Solution: Reset the terminal:

reset
# or
clear

Related Workflows

• Getting Started - Initial setup and configuration
• Features - Detailed feature documentation
• Troubleshooting - More issue solutions