Quick Start Guide

Get up and running with s9s in just a few minutes! This guide covers the basics to help you start managing your SLURM cluster more efficiently.

🚀 First Launch

With SLURM Cluster

s9s connects via the SLURM REST API, which requires slurmrestd running on your cluster (default port 6820). See the Installation Guide for setup instructions.

Copy
# Launch s9s
s9s

# Or connect to a specific cluster
s9s --cluster production

Without SLURM (Mock Mode)

Try s9s without a SLURM cluster:

Copy
# Launch in mock mode with simulated data
S9S_ENABLE_MOCK=1 s9s --mock

Mock mode is perfect for:

• Learning s9s navigation
• Testing workflows
• Demo purposes
• Development and testing

🎯 Basic Navigation

View Switching

s9s organizes information into focused views. Switch between them using:

• Tab - Cycle forward through views
• Shift+Tab - Cycle backward through views
• 1 - Jobs view
• 2 - Nodes view
• 3 - Partitions view
• 4 - Reservations view
• 5-7 - QoS, Accounts, Users
• 8 - Dashboard view
• 9 - Health view
• 0 - Performance view

Common views:

1. Jobs - Monitor and manage jobs
2. Nodes - View and manage compute nodes
3. Partitions - Monitor partitions and queues
4. Reservations - Resource reservations
5. QoS - Quality of Service policies
6. Accounts - Account hierarchy
7. Users - View user accounts
8. Dashboard - Cluster overview with metrics
9. Health - Cluster health monitoring
10. Performance - Performance metrics

Essential Keyboard Shortcuts

See Keyboard Shortcuts for complete reference.

📊 Dashboard View

The Dashboard is your cluster command center:

What You See

• Cluster Overview - Health status, CPU/Memory usage
• Jobs Summary - Job states and queue depth
• Nodes Summary - Node availability and utilization
• Partition Status - Top partitions
• Alerts & Issues - System health warnings
• Performance Trends - Historical metrics

Quick Actions

📊 Jobs View

The Jobs view is where you'll manage your workload:

View Jobs

Copy
# Launch s9s and switch to jobs view with keyboard shortcut
# Press 1 to jump to Jobs view

Common Operations

Filtering Jobs

Use / to filter jobs:

Copy
# Examples:
/RUNNING        # Show only running jobs
/gpu            # Find jobs with "gpu" in any field
/p:gpu          # Filter by partition "gpu"
/alice          # Find jobs with "alice" in any field

Press ESC to clear filters.

For complex filtering, press Ctrl+F to open global search across all entity types (available in all data views). In data views, you can also use field-specific syntax in the filter bar:

Copy
state=RUNNING partition=gpu
user=alice priority>500
nodes>=8

💻 Nodes View

Monitor and manage compute nodes:

Common Operations

Node States

• IDLE (Green) - Available for jobs
• ALLOCATED (Blue) - Running jobs
• MIXED (Blue) - Partially allocated
• DRAIN (Red) - Scheduled for maintenance
• DOWN (Red) - Offline/unavailable

Resource Usage

Nodes display dual-bar visualization:

Copy
CPU: ████████░░░░░░░░ 8/16 (Load: 7.5)
     ^^^^^^^^          Actual usage (solid)
             ░░░░░░    Allocated but unused (hollow)

🎯 Practical Examples

Example 1: Submit a New Job

1. Press s in Jobs view
2. Fill in job submission wizard:
   • Job name
   • Partition
   • Number of nodes/CPUs
   • Time limit
   • Script or command
3. Review and submit

Example 2: Cancel Failed Jobs

1. In Jobs view, press / and type FAILED
2. Navigate to a job with arrow keys
3. Press c to cancel
4. Confirm with y (or use batch operations for multiple)

Example 3: SSH to a Node

1. Switch to Nodes view (press 2)
2. Find your node (use /nodename to filter)
3. Press s to open SSH menu
4. Select "Quick Connect"
5. Interactive SSH session opens

Example 4: Monitor GPU Jobs

1. In Jobs view, press /
2. Type p:gpu to filter GPU partition
3. Press Enter to apply
4. Press Enter on any job for GPU details

Example 5: Batch Cancel Pending Jobs

1. In Jobs view, press v/V for multi-select mode
2. Navigate with arrow keys
3. Press Space to select specific jobs
4. Or press b/B and choose "Cancel all PENDING"

🔍 Advanced Features

Quick Filter

Press / to filter the current view:

Copy
# Type to filter — matches across all columns
/ → type "gpu001"
# Shows matching rows in the current view

Global Search

Press Ctrl+F in any data view to open global search, which searches across all entity types (jobs, nodes, partitions, users, accounts, QoS, reservations).

Batch Operations

Select multiple items:

1. Press v/V to enter multi-select mode
2. Press Space on items to select
3. Press Ctrl+A to select all visible
4. Press b/B for batch menu
5. Choose operation (cancel, hold, release, etc.)

⚡ Command Mode

Press : to enter command mode (vim-style) with intelligent autocomplete:

Basic Commands

Copy
:help              # Show help
:quit              # Exit s9s
:nodes        # Switch to nodes view
:refresh           # Force refresh

Commands with Autocomplete

Copy
# Tab completion for commands
:req<Tab>          # Completes to :requeue
:dr<Tab>           # Completes to :drain

# Tab completion for arguments
:cancel <Tab>      # Shows available job IDs
:drain <Tab>       # Shows available node names
:requeue <Tab>     # Shows available job IDs

# Full examples
:cancel 12345      # Cancel job 12345
:drain node01      # Drain node01
:requeue 67890     # Requeue failed job

Pro Tip: Autocomplete uses cached data from your views, so you'll see real job IDs and node names from your cluster without extra API calls.

See Commands Reference for complete command documentation.

🎨 Quick Customization

Grouping (Nodes)

Copy
Press g/G in Nodes view
Choose: partition, state, features, or none
Press Space to expand/collapse groups

📝 Next Steps

Now that you know the basics, explore:

1. Views Overview - Detailed view documentation
2. Keyboard Shortcuts - Complete shortcuts
3. Job Management - Advanced job operations
4. Configuration - Customize s9s
5. Filtering Guide - Master advanced filters

💡 Pro Tips

1. Practice with mock mode - S9S_ENABLE_MOCK=1 s9s --mock is risk-free
2. Use keyboard shortcuts - Faster than mouse for everything
3. Multi-select is powerful - Batch operations save time
4. Use quick filters - Press / to filter any view instantly
5. Context help - Press ? in any view for specific shortcuts
6. Group nodes - Makes large clusters manageable
7. SSH from UI - No need to remember node names
8. Watch job output - Press o/O for real-time log streaming

🆘 Getting Help

• In-app help: Press ? anywhere for context-sensitive help
• Help modal: Press F1 for help
• Full docs: https://s9s.dev/docs
• Troubleshooting: Troubleshooting Guide
• GitHub Issues: Report bugs

Common Questions

Q: How do I exit s9s? A: Press q to quit.

Q: Can I use s9s without SLURM? A: Yes! Use S9S_ENABLE_MOCK=1 s9s --mock for a fully functional demo mode.

Q: How do I cancel multiple jobs? A: Use multi-select (v/V), select jobs with Space, then press b/B for batch operations.

Q: Can I SSH to nodes from s9s? A: Yes! Press s in Nodes view for SSH options.

Q: How do I filter by partition? A: Use / and type p:partitionname for quick filter, or press Ctrl+F for global search across all resources.

Q: Is there a way to save my filters? A: Saved filters are a planned feature. For now, use / to quickly re-enter filters in any view.

Q: Can I customize colors/theme? A: Yes, see Configuration Guide for theme options.