Getting Started with Shell App

This guide walks you through setting up and using the Shell App for the first time.

Prerequisites

Before using the Shell App, ensure you have:

• Access to a FlowState environment (web or desktop)
• A running shell server (automatically provided in Electron, or ws://localhost:3001 for web)
• Appropriate workspace permissions to create terminal sessions

Accessing the App

From the App Launcher

1. Open the FlowState app launcher
2. Click on Terminal Shell (emerald icon)
3. The app opens at /shell/terminal

From the Bottom Panel

The Shell App can also be used as an embedded panel in other FlowState applications:

1. Click the terminal icon in the bottom panel toolbar
2. The terminal panel expands from the bottom of the screen
3. Create or select a session to begin working

Initial Setup

Step 1: Verify Connection Status

When the Shell App loads, check the connection status indicator in the header:

If disconnected, the app will automatically attempt to reconnect. You can also click the Connect button manually.

Step 2: Create Your First Terminal Session

1. Click the New Terminal button (or press Ctrl+Shift+` on Windows/Linux, Cmd+Shift+` on macOS)
2. In the session form, enter:
   • Display Name: A descriptive name (e.g., "Dev Server", "Build Terminal")
   • Server URL: Usually the default ws://localhost:3001 works
3. Optionally, associate the session with a context:
   • Select a Workspace
   • Select a Project (filters milestones)
   • Select a Milestone (filters tasks)
   • Select a Task (for command tracking)
4. Click Connect to create the session

Step 3: Start Using the Terminal

Once connected, you have a fully functional terminal:

• Type commands and press Enter to execute
• Use arrow keys to navigate command history
• Terminal output supports full ANSI colors and formatting
• The session persists across page refreshes

# Example: Check your current directory
pwd

# Example: List files
ls -la

# Example: Run a development server
npm run dev

Understanding the Interface

Main Terminal View

+------------------+--------------------------------+
|                  |                                |
|  Session List    |      Terminal Display          |
|  (Sidebar)       |                                |
|                  |                                |
|  [Session 1]     |  $ pwd                        |
|  [Session 2]     |  /home/user/project           |
|  [+ New]         |  $                            |
|                  |                                |
+------------------+--------------------------------+

Session List Sidebar

The sidebar on the left shows all your terminal sessions:

• Click a session to switch to it
• The active session is highlighted
• Right-click for context actions (rename, close, delete)
• Click + to create a new session

Terminal Display

The main area shows the active terminal:

• Full xterm.js terminal emulation
• Supports colors, cursor movement, and special characters
• Resize automatically when window size changes

Keyboard Shortcuts

Master these shortcuts to work efficiently:

Next Steps

Now that you have the Shell App set up:

• Explore Features to learn about session management and context linking
• Check out Running Commands for detailed workflow guidance
• Review the FAQ for answers to common questions
• See Troubleshooting if you encounter issues