s9s

module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 8, 2026 License: MIT

README

s9s - Terminal UI for SLURM

s9s logo

Release CI codecov Go Report Go Reference License Documentation

s9s provides a terminal interface for managing SLURM clusters, inspired by the popular k9s Kubernetes CLI. It allows HPC administrators and users to monitor and manage jobs, nodes, and cluster resources efficiently from the terminal.

📚 Documentation

✨ Features

  • Real-time Monitoring: Live updates of jobs, nodes, and cluster status
  • Multi-View Interface: Dedicated views for jobs, nodes, partitions, users, QoS, and more
  • Job Management: Submit, cancel, hold, release, and monitor jobs
  • Batch Operations: Perform actions on multiple jobs simultaneously
  • Advanced Filtering: Powerful search and filter capabilities
  • Command Mode with Autocomplete: Vim-style : commands with Tab completion for commands and arguments
  • SSH Integration: Connect directly to compute nodes
  • Export Capabilities: Export data in CSV, JSON, Markdown, HTML formats
  • Real-time Job Log Streaming: Live job output monitoring with filtering
  • Plugin System: Extensible architecture for custom functionality
  • Cluster Performance Monitoring: Real-time cluster-wide metrics and resource utilization
  • Vim-like Navigation: Familiar keyboard shortcuts for power users
  • Mock Mode: Built-in SLURM simulator for development and testing

🚀 Quick Start

Prerequisites
  • Go 1.19 or higher
  • Access to a SLURM cluster (or use mock mode)
  • Terminal with 256 color support
Installation
curl -sSL https://get.s9s.dev | bash
Using Go Install
go install github.com/jontk/s9s/cmd/s9s@latest
From Source
git clone https://github.com/jontk/s9s.git
cd s9s
go build -o s9s cmd/s9s/main.go
sudo mv s9s /usr/local/bin/
Basic Usage
# Connect to your SLURM cluster
s9s

# Use mock mode for testing (no SLURM required)
s9s --mock

# Connect to a specific cluster
s9s --cluster production

# Enable debug logging
s9s --debug
Configuration

Run the interactive setup wizard for first-time configuration:

s9s setup

The wizard will guide you through:

  • 🏢 Cluster connection settings
  • 🔐 Authentication configuration
  • 🔒 Secure credential storage
  • ⚡ Performance optimization
Manual Configuration

s9s looks for configuration in the following order:

  1. ~/.s9s/config.yaml
  2. ~/.config/s9s/config.yaml
  3. Environment variables
  4. Command-line flags

Example configuration:

# ~/.s9s/config.yaml
clusters:
  production:
    url: https://slurm-api.example.com
    token: ${SLURM_TOKEN}
    default: true
  
  development:
    url: https://slurm-dev.example.com
    auth:
      username: ${SLURM_USER}
      password: ${SLURM_PASS}

preferences:
  theme: dark
  refreshInterval: 5s
  defaultView: jobs

🎮 Key Bindings

Global
Key Action
? Show help
q Quit
: Command mode
/ Search
Tab Switch view
Ctrl+r Force refresh
Command Mode with Autocomplete

Press : to enter vim-style command mode with intelligent Tab completion:

# Tab completes command names
:req<Tab>          → :requeue

# Tab shows available job IDs
:cancel <Tab>      → Shows: 12345, 12346, 12347...

# Tab shows available node names
:drain <Tab>       → Shows: node01, node02, node03...

# Full commands
:cancel 12345      # Cancel job 12345
:drain node01      # Drain node01
:requeue 67890     # Requeue failed job
Jobs View
Key Action
c Cancel job
h Hold job
r Release job
d Show job details
o View job output
s Submit new job
b Batch operations
m Toggle auto-refresh
Nodes View
Key Action
d Drain node
r Resume node
s SSH to node
i Node info

🏗️ Architecture

s9s follows a modular architecture with clear separation of concerns:

cmd/s9s/          # Main application entry point
internal/
  ├── app/        # Application lifecycle management
  ├── dao/        # Data Access Objects (SLURM client abstraction)
  ├── views/      # Terminal UI views
  ├── config/     # Configuration management
  ├── ui/         # UI components and utilities
  ├── monitoring/ # Health monitoring and alerts
  ├── performance/# Performance profiling and optimization
  └── plugins/    # Plugin system implementation
pkg/
  └── mock/       # Mock SLURM implementation for testing

For more information about the project structure, see the docs/ directory.

🔧 Development

Setup Development Environment
# Clone the repository
git clone https://github.com/jontk/s9s.git
cd s9s

# Install dependencies
go mod download

# Run tests
go test ./...

# Run with mock data
go run cmd/s9s/main.go --mock

# Build binary
go build -o s9s cmd/s9s/main.go
Running Tests
# Unit tests
go test ./...

# Integration tests
go test -tags=integration ./test/integration

# Benchmarks
go test -bench=. ./test/performance

# Coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out
Debug Mode

Enable debug logging to troubleshoot issues:

s9s --debug

# Or set environment variable
export S9S_DEBUG=true
s9s

Debug logs are written to ~/.s9s/debug.log.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide
  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Make your changes
  4. Run tests (go test ./...)
  5. Commit your changes (git commit -m 'Add amazing feature')
  6. Push to the branch (git push origin feature/amazing-feature)
  7. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

  • Inspired by k9s - Kubernetes CLI
  • Built with tview - Terminal UI framework
  • SLURM - HPC workload manager

Made with ❤️ for the HPC community

Directories

Path Synopsis
cmd
s9s command
Package main provides the entry point for the s9s command-line interface.
 Package main provides the entry point for the s9s command-line interface.
test-cli command
Package main provides a test CLI for demonstrating s9s functionality.
 Package main provides a test CLI for demonstrating s9s functionality.
internal
app
Package app provides the main application logic and lifecycle management for s9s.
 Package app provides the main application logic and lifecycle management for s9s.
auth
Package auth provides authentication and authorization functionality for s9s.
 Package auth provides authentication and authorization functionality for s9s.
cli
Package cli provides command-line interface command handlers and execution.
 Package cli provides command-line interface command handlers and execution.
config
Package config provides configuration loading, validation, and management.
 Package config provides configuration loading, validation, and management.
dao
Package dao provides data access objects and interfaces for SLURM cluster management.
 Package dao provides data access objects and interfaces for SLURM cluster management.
debug
Package debug provides debugging utilities and logging for development.
 Package debug provides debugging utilities and logging for development.
discovery
Package discovery provides automatic discovery of SLURM cluster endpoints.
 Package discovery provides automatic discovery of SLURM cluster endpoints.
errs
Package errs provides structured error types and handling for s9s.
 Package errs provides structured error types and handling for s9s.
export
fileperms
Package fileperms provides type-safe file permission constants to avoid hardcoded octal values that trigger gosec warnings.
 Package fileperms provides type-safe file permission constants to avoid hardcoded octal values that trigger gosec warnings.
layouts
Package layouts provides layout management and dashboard widget organization.
 Package layouts provides layout management and dashboard widget organization.
logging
Package logging provides structured logging capabilities using zerolog.
 Package logging provides structured logging capabilities using zerolog.
mathutil
Package mathutil provides mathematical utility functions and type conversions.
 Package mathutil provides mathematical utility functions and type conversions.
mock
Package mock provides mock client validation and mock mode utilities.
 Package mock provides mock client validation and mock mode utilities.
monitoring
Package monitoring provides cluster monitoring and alert management.
 Package monitoring provides cluster monitoring and alert management.
notifications
Package notifications provides notification management and alert handling.
 Package notifications provides notification management and alert handling.
output
Package output provides functionality for reading SLURM job output files.
 Package output provides functionality for reading SLURM job output files.
performance
Package performance provides performance optimization and monitoring tools.
 Package performance provides performance optimization and monitoring tools.
plugin
Package plugin provides the plugin system interface and base types.
 Package plugin provides the plugin system interface and base types.
plugins
Package plugins provides the plugin management system for s9s.
 Package plugins provides the plugin management system for s9s.
preferences
Package preferences provides user preference management and persistence.
 Package preferences provides user preference management and persistence.
security
Package security provides security utilities for validating command paths, file paths, and preventing injection attacks.
 Package security provides security utilities for validating command paths, file paths, and preventing injection attacks.
setup
Package setup provides interactive setup wizard for s9s configuration.
 Package setup provides interactive setup wizard for s9s configuration.
ssh
Package ssh provides SSH authentication and connection utilities.
 Package ssh provides SSH authentication and connection utilities.
streaming
Package streaming provides streaming buffer and output management.
 Package streaming provides streaming buffer and output management.
testapi
Package testapi provides test utilities and application state export for testing.
 Package testapi provides test utilities and application state export for testing.
ui/components
Package components provides reusable UI components for the s9s interface.
 Package components provides reusable UI components for the s9s interface.
ui/filters
Package filters provides advanced filtering and query parsing for UI views.
 Package filters provides advanced filtering and query parsing for UI views.
ui/navigation
Package navigation provides navigation management and keyboard input handling.
 Package navigation provides navigation management and keyboard input handling.
ui/styles
Package styles provides consistent styling for UI components that works with terminal color themes like Catppuccin, Dracula, Gruvbox, etc.
 Package styles provides consistent styling for UI components that works with terminal color themes like Catppuccin, Dracula, Gruvbox, etc.
ui/views/settings
Package settings provides settings views for configuring s9s options.
 Package settings provides settings views for configuring s9s options.
ui/widgets
Package widgets provides specialized UI widgets for s9s interface.
 Package widgets provides specialized UI widgets for s9s interface.
version
Package version provides version information for s9s
 Package version provides version information for s9s
views
Package views provides display views for various s9s data types.
 Package views provides display views for various s9s data types.
pkg
slurm
Package slurm provides SLURM client implementation and mock for testing.
 Package slurm provides SLURM client implementation and mock for testing.
plugins
observability
observability/alerts
Package alerts provides real-time alerting and notification capabilities for monitoring system metrics and resource utilization.
 Package alerts provides real-time alerting and notification capabilities for monitoring system metrics and resource utilization.
observability/analysis
Package analysis provides advanced analytics capabilities for resource utilization and efficiency analysis.
 Package analysis provides advanced analytics capabilities for resource utilization and efficiency analysis.
observability/cmd/plugin command
Package main provides the observability plugin export functionality.
 Package main provides the observability plugin export functionality.
observability/config
Package config provides configuration management for the observability plugin.
 Package config provides configuration management for the observability plugin.
observability/endpoints
Package endpoints provides external HTTP API endpoints for accessing observability data.
 Package endpoints provides external HTTP API endpoints for accessing observability data.
observability/historical
Package historical provides time-series data collection and analysis capabilities.
 Package historical provides time-series data collection and analysis capabilities.
observability/initialization
Package initialization provides centralized component initialization and lifecycle management for the observability plugin.
 Package initialization provides centralized component initialization and lifecycle management for the observability plugin.
observability/logging
Package logging provides a simple logging infrastructure for the observability plugin It supports file-based logging with different levels and structured output
 Package logging provides a simple logging infrastructure for the observability plugin It supports file-based logging with different levels and structured output
observability/metrics
Package metrics provides comprehensive metrics collection and instrumentation for the observability plugin itself.
 Package metrics provides comprehensive metrics collection and instrumentation for the observability plugin itself.
observability/models
Package models defines data structures and types for representing metrics, nodes, jobs, and other observability entities.
 Package models defines data structures and types for representing metrics, nodes, jobs, and other observability entities.
observability/overlays
Package overlays provides dynamic metric overlay functionality for enhancing existing S9S views with real-time observability data.
 Package overlays provides dynamic metric overlay functionality for enhancing existing S9S views with real-time observability data.
observability/prometheus
Package prometheus provides Prometheus client functionality with advanced features including caching, circuit breaking, connection pooling, and batch query processing.
 Package prometheus provides Prometheus client functionality with advanced features including caching, circuit breaking, connection pooling, and batch query processing.
observability/security
Package security provides comprehensive security mechanisms for the observability plugin, including audit logging, rate limiting, request validation, and secrets management.
 Package security provides comprehensive security mechanisms for the observability plugin, including audit logging, rate limiting, request validation, and secrets management.
observability/subscription
Package subscription provides real-time data subscription and notification capabilities.
 Package subscription provides real-time data subscription and notification capabilities.
observability/test command
Package main provides test utilities for the observability plugin.
 Package main provides test utilities for the observability plugin.
observability/views
Package views provides user interface components and widgets for displaying observability data within the S9S application.
 Package views provides user interface components and widgets for displaying observability data within the S9S application.
observability/views/widgets
Package widgets provides UI widgets for the observability plugin.
 Package widgets provides UI widgets for the observability plugin.
test
tui

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.