Web CLI

A powerful web-based interface for executing commands on local and remote Linux servers. Built with Go and React with Material-UI for a professional, modern user experience.

Main dashboard with feature cards for easy navigation

📋 Table of Contents

Features
Tech Stack
Screenshots
Prerequisites
Installation
Quick Start
Usage
API Documentation
Configuration
Security
Deployment
Development
Contributing
License

✨ Features

Core Functionality

Web-Based Interface: Professional Material-UI dashboard accessible from any browser
Theme Support: Dark and light mode toggle with preferences saved locally
Multi-Platform: Compiled binaries for Linux x64, macOS Intel, and macOS Apple Silicon

Command Execution

Local Commands: Execute bash commands on your local server with real-time output
Remote Commands: Connect and execute commands on remote servers via SSH
User Selection: Run commands as different users (current, root, or custom)
Sudo Support: Secure password dialog for root command execution

Server & SSH Management

Admin Panel: Full management interface with tabbed sections
SSH Key Management: CRUD operations for SSH private keys
Server Management: Manage remote servers with hostname, IP, port, and username
Hostname Validation: Automatic validation according to hostname conventions

Command Templates & History

Command Templates: Save frequently-used commands for quick re-execution
Command Type Management: Visual indicators (Local/Remote) with type switching
Smart Navigation: Execute button routes to appropriate page based on command type
Command History: Complete execution history with output, exit codes, and timing

Environment Variables

Secure Storage: Store sensitive environment variables with AES-256-GCM encryption
Masked Display: Values masked by default in API responses
Script Injection: Inject stored env vars into script executions

Bash Scripts

Script Library: Store and manage reusable bash scripts
Local & Remote Execution: Execute scripts on local or remote servers
Script Presets: Save execution configurations (server, SSH key, user, env vars)
Environment Integration: Inject stored environment variables into scripts

Security

Authentication: HTTP Basic Auth and Bearer token support (configurable)
TLS/HTTPS Support: Native TLS support with optional HTTPS enforcement
Security Headers: X-Frame-Options, X-Content-Type-Options, X-XSS-Protection, Referrer-Policy
SSH Host Key Verification: Proper host key checking against known_hosts with TOFU support
Input Validation: Comprehensive validation for all user inputs
Encrypted Database: SQLite with AES-256-GCM encryption for sensitive data
bcrypt Password Hashing: Secure password hashing with cost factor 12
HTTP Timeouts: Protection against slowloris and DoS attacks
CORS Policy: Restrictive CORS with configurable origins
Secure Password Handling: SSH passwords never stored in command history
Automatic Encryption: All SSH keys, scripts, and env variables encrypted at rest
Entropy Verification: System entropy check before cryptographic key generation (Linux)
Database Migrations: Automatic schema versioning and migration system

🛠 Tech Stack

Backend

Go 1.21+: High-performance backend server
Gorilla Mux: HTTP router for API endpoints
Viper: Configuration management with env, file, and flag support
SQLite: Embedded database with migration support
golang.org/x/crypto/ssh: SSH client with host key verification
golang.org/x/crypto/bcrypt: Secure password hashing
AES-256-GCM: Military-grade encryption for sensitive data
Authentication Middleware: HTTP Basic Auth and Bearer token support
Security Middleware: HTTPS enforcement and security headers
Input Validation: Comprehensive validation for security

Frontend

React 18: Modern UI library
React Router v6: Client-side routing
Material-UI (MUI) v5: Professional component library
Vite: Fast build tool and dev server
Emotion: CSS-in-JS styling

📸 Screenshots

Dashboard

Main dashboard with feature cards for easy navigation

Local Command Execution

Execute commands on your local server with real-time output

Remote Command Execution

Connect to remote servers via SSH and execute commands

Admin Panel - SSH Keys

Manage SSH private keys for server authentication

Admin Panel - Servers

Configure and manage remote servers

Saved Commands

Save and reuse frequently-used command templates with type indicators

Command History

View complete execution history with output and timing

📦 Prerequisites

Go: Version 1.21 or higher (Download)
Node.js: Version 18 or higher (Download)
npm: Version 8 or higher (comes with Node.js)

🚀 Installation

Clone the Repository

git clone https://github.com/pozgo/web-cli.git
cd web-cli

Install Dependencies

Backend

go mod download

Frontend

cd frontend
npm install
cd ..

⚡ Quick Start

Build and Run

# Build the application
./build.sh

# Run the server
./web-cli

Access the application at http://localhost:7777

Using Management Script

# Start the server
./manage.sh start

# Stop the server
./manage.sh stop

# Check status
./manage.sh status

📖 Usage

Local Command Execution

Navigate to Local Commands from the dashboard
Enter your bash command
Select the user to run as (current, root, or custom)
Click Execute Command
View real-time output

Remote Command Execution

First, add SSH keys and servers in the Admin Panel
Navigate to Remote Execution
Select a server from the dropdown
Choose an SSH key (optional, password fallback available)
Enter your command and click Execute

Saved Command Templates

Execute any command and check "Save command as template"
Access saved commands from the Saved Commands page
Edit command type (Local/Remote) and details
Execute saved commands with one click

📚 API Documentation

Web CLI provides a comprehensive RESTful API for programmatic access to all features. Perfect for automation, CI/CD pipelines, and integration with other tools.

🚀 Quick Start

Base URL: http://localhost:7777/api

Example Request:

curl http://localhost:7777/api/health
# Response: {"status":"ok"}

📋 API Endpoints Overview

Category	Endpoints	Description
Health	1 endpoint	Server health check
SSH Keys	5 endpoints	Manage SSH private keys
Servers	5 endpoints	Manage remote servers
Local Users	5 endpoints	Manage local user accounts
System Info	1 endpoint	Get current system user
Commands	1 endpoint	Execute local/remote commands
Saved Commands	5 endpoints	Manage command templates
History	2 endpoints	View execution history
Environment Variables	5 endpoints	Manage encrypted env variables
Bash Scripts	6 endpoints	Manage and execute scripts
Script Presets	5 endpoints	Manage execution presets

Total: 41 RESTful API endpoints

📖 Complete Documentation

For detailed API documentation including:

✅ All 41 endpoints with full descriptions
✅ Request/response examples with cURL commands
✅ Field descriptions and validation rules
✅ Error response formats and status codes
✅ Security considerations and best practices
✅ Authentication guidance for production
✅ Quick reference table for all endpoints

👉 See API.md for complete API reference

💡 Common Use Cases

Note: If authentication is enabled, add -u username:password or -H "Authorization: Bearer token" to all requests.

Execute a local command:

curl -u admin:password -X POST http://localhost:7777/api/commands/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "df -h", "user": "root"}'

Execute a remote command via SSH:

curl -u admin:password -X POST http://localhost:7777/api/commands/execute \
  -H "Content-Type: application/json" \
  -d '{
    "command": "uptime",
    "is_remote": true,
    "server_id": 1,
    "ssh_key_id": 2
  }'

List command history:

curl -u admin:password "http://localhost:7777/api/history?limit=10&server=local"

Using Bearer Token:

curl -H "Authorization: Bearer your-api-token" \
  -X POST http://localhost:7777/api/commands/execute \
  -H "Content-Type: application/json" \
  -d '{"command": "uptime", "user": "current"}'

⚙️ Configuration

Command-Line Flags

./web-cli [options]

Options:
  -port int              Port to listen on (default: 7777)
  -host string           Host to bind to (default: 0.0.0.0)
  -frontend string       Path to frontend build files (default: ./frontend/dist)
  -db string             Path to database file (default: ./data/web-cli.db)
  -encryption-key string Path to encryption key file (default: ./.encryption_key)
  -tls-cert string       Path to TLS certificate file (enables HTTPS)
  -tls-key string        Path to TLS private key file
  -require-https         Require HTTPS when auth is enabled (reject HTTP requests)

Environment Variables

All configuration options can be set via environment variables:

# Standard environment variables
PORT=8080 HOST=localhost ./web-cli

# WEBCLI-prefixed variables (recommended)
WEBCLI_PORT=8080
WEBCLI_HOST=localhost
WEBCLI_DATABASE_PATH=/var/lib/web-cli/web-cli.db
WEBCLI_ENCRYPTION_KEY_PATH=/etc/web-cli/encryption.key
WEBCLI_TLS_CERT_PATH=/etc/ssl/certs/web-cli.crt
WEBCLI_TLS_KEY_PATH=/etc/ssl/private/web-cli.key
WEBCLI_REQUIRE_HTTPS=true

Configuration File

Web CLI supports configuration files in YAML, JSON, or TOML format. Configuration files are searched in the following locations (first found is used):

./config.yaml (current directory)
./config/config.yaml (config subdirectory)
/etc/web-cli/config.yaml (system config)
~/.config/web-cli/config.yaml (user config)

Example config.yaml:

port: 7777
host: "0.0.0.0"
frontend_path: "./assets/frontend"
database_path: "./data/web-cli.db"
encryption_key_path: "./.encryption_key"
tls_cert_path: "/etc/ssl/certs/web-cli.crt"
tls_key_path: "/etc/ssl/private/web-cli.key"
require_https: true

Configuration Priority

Command-line flags (highest priority)
Environment variables
Configuration file
Default values (lowest priority)

🔒 Security

Authentication (Production Ready)

Important: Authentication is disabled by default for development convenience.

For production deployments, enable authentication:

# Enable authentication
export AUTH_ENABLED=true

# Option 1: HTTP Basic Authentication
export AUTH_USERNAME="admin"
export AUTH_PASSWORD="your-secure-password"

# Option 2: API Token (Bearer)
export AUTH_API_TOKEN="your-api-token-here"

Features:

HTTP Basic Authentication support
Bearer token (API token) support
Constant-time credential comparison (prevents timing attacks)
Supports both methods simultaneously (token takes precedence)

Usage Examples:

# Basic Auth
curl -u admin:password http://localhost:7777/api/health

# Bearer Token
curl -H "Authorization: Bearer your-token" http://localhost:7777/api/health

TLS/HTTPS Support

Native TLS support for encrypted connections:

# Enable TLS with certificate and key
./web-cli -tls-cert /path/to/cert.pem -tls-key /path/to/key.pem

# Or via environment variables
WEBCLI_TLS_CERT_PATH=/path/to/cert.pem \
WEBCLI_TLS_KEY_PATH=/path/to/key.pem \
./web-cli

# Enforce HTTPS when authentication is enabled
./web-cli -tls-cert cert.pem -tls-key key.pem -require-https

Features:

Native Go TLS implementation (no reverse proxy required)
Automatic HTTPS when certificate and key are provided
Optional HTTPS enforcement (rejects HTTP requests)
Works with any TLS certificate (self-signed, Let's Encrypt, etc.)

Generate self-signed certificate for testing:

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem \
  -days 365 -nodes -subj "/CN=localhost"

SSH Host Key Verification

Proper host key verification for secure SSH connections:

Verifies SSH host keys against ~/.ssh/known_hosts
Supports "trust on first use" mode for development
Detects man-in-the-middle attacks (host key mismatch)
Automatically saves new trusted host keys
Thread-safe implementation

Configuration:

Strict Mode (production): Rejects unknown hosts
Trust-on-First-Use (development): Automatically trusts new hosts

Input Validation

All user inputs are validated before processing:

IP addresses (IPv4/IPv6)
Hostnames (RFC 1123 compliant)
Port numbers (1-65535)
SSH private keys (format validation)
Unix usernames (alphanumeric, dash, underscore)
Command names (no null bytes or newlines)

HTTP Security

Server configured with proper timeouts:

ReadTimeout:  15 * time.Second  // Prevents slowloris attacks
WriteTimeout: 15 * time.Second  // Prevents slow writes  
IdleTimeout:  60 * time.Second  // Prevents idle connections

CORS Policy:

Default: localhost only
Production: Configure via CORS_ALLOWED_ORIGINS environment variable

# Single origin
export CORS_ALLOWED_ORIGINS="https://web-cli.example.com"

# Multiple origins (comma-separated)
export CORS_ALLOWED_ORIGINS="https://web-cli.example.com,https://admin.example.com"

Database Encryption

All sensitive data is encrypted using AES-256-GCM:

SSH private keys encrypted at rest
Command history (commands and output) encrypted
Encryption key auto-generated on first run
Key stored in .encryption_key with 600 permissions

Encryption Key Management

Important:

Backup your .encryption_key file - data cannot be recovered without it
For production, use environment variable instead of file

Generate a new encryption key:

# macOS/Linux
openssl rand -base64 32

# Or using dd and base64
dd if=/dev/urandom bs=32 count=1 2>/dev/null | base64

# Output example: 7xK9mP2vQ8nL4wR6tY5uE3sA1zD0cF8bG7hJ9kM6nP4=

Use the generated key:

# Option 1: Environment variable (recommended for production)
export ENCRYPTION_KEY="7xK9mP2vQ8nL4wR6tY5uE3sA1zD0cF8bG7hJ9kM6nP4="
./web-cli

# Option 2: Save to file (auto-generated on first run if not exists)
echo "7xK9mP2vQ8nL4wR6tY5uE3sA1zD0cF8bG7hJ9kM6nP4=" > .encryption_key
chmod 600 .encryption_key
./web-cli

Password Security

Sudo passwords only used for command execution
SSH passwords used for authentication fallback
Passwords are never stored in command history
Passwords cleared from memory after use

Database Migrations

Automatic schema versioning
Migrations run on startup
Safe to restart - migrations only run once
Current schema version: 14

🌐 Deployment

Linux Server

# Build for Linux
./build.sh all

# Copy to server
scp bin/web-cli-linux-x64 user@server:/opt/web-cli/web-cli

# Run on server
ssh user@server
cd /opt/web-cli
./web-cli

systemd Service

Create /etc/systemd/system/web-cli.service:

[Unit]
Description=Web CLI Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/web-cli
ExecStart=/opt/web-cli/web-cli
Restart=on-failure

# Security Configuration (REQUIRED for production)
Environment=AUTH_ENABLED=true
Environment=AUTH_USERNAME=admin
Environment=AUTH_PASSWORD=your-secure-password-here
Environment=CORS_ALLOWED_ORIGINS=https://web-cli.yourdomain.com
Environment=ENCRYPTION_KEY=your-encryption-key-here

[Install]
WantedBy=multi-user.target

Enable and start:

sudo systemctl enable web-cli
sudo systemctl start web-cli
sudo systemctl status web-cli

Production Deployment Checklist

Before deploying to production, ensure:

Security Configuration:

✅ Authentication enabled: Set AUTH_ENABLED=true
✅ Strong credentials: Configure AUTH_USERNAME and AUTH_PASSWORD (or AUTH_API_TOKEN)
✅ SSH host key verification: Enabled by default (uses ~/.ssh/known_hosts)
✅ CORS restricted: Set CORS_ALLOWED_ORIGINS to your domain(s)
✅ HTTP timeouts: Configured automatically (prevents DoS attacks)
✅ Input validation: All inputs validated automatically

Additional Requirements:

HTTPS enabled: Use native TLS (-tls-cert, -tls-key) or reverse proxy
Encryption key backup: Backup .encryption_key - data cannot be recovered without it
Security scan: Run gosec ./... or similar security scanner
Monitor logs: Check for authentication failures and errors
Firewall configured: Restrict access to authorized IPs if possible

Production Environment Variables:

# Authentication (REQUIRED for production)
AUTH_ENABLED=true
AUTH_USERNAME=admin
AUTH_PASSWORD=$(openssl rand -base64 32)  # Or your secure password
# OR use API token
AUTH_API_TOKEN=$(openssl rand -base64 32)

# CORS Policy (REQUIRED for production)
CORS_ALLOWED_ORIGINS=https://web-cli.yourdomain.com

# Encryption (REQUIRED)
ENCRYPTION_KEY=$(openssl rand -base64 32)

# TLS/HTTPS (RECOMMENDED for production)
WEBCLI_TLS_CERT_PATH=/etc/ssl/certs/web-cli.crt
WEBCLI_TLS_KEY_PATH=/etc/ssl/private/web-cli.key
WEBCLI_REQUIRE_HTTPS=true

# Server Config (Optional)
WEBCLI_PORT=7777
WEBCLI_HOST=0.0.0.0

Testing Authentication:

# Should fail (no auth)
curl http://localhost:7777/api/health

# Should succeed with Basic Auth
curl -u admin:password http://localhost:7777/api/health

# Should succeed with Bearer token
curl -H "Authorization: Bearer your-token" http://localhost:7777/api/health

Docker

Web CLI is available as a Docker image for easy deployment.

Image Details:

Registry: Docker Hub (polinux/web-cli)
Base Image: Debian Bookworm (slim) - provides full bash support for script execution
Platforms: linux/amd64, linux/arm64
Size: ~100MB compressed

Quick Start with Docker Compose:

# Clone the repository
git clone https://github.com/pozgo/web-cli.git
cd web-cli

# Start with default settings
docker compose up -d

# View logs
docker compose logs -f

Access: http://localhost:7777

Build Locally:

# Build the image
docker compose build

# Or build directly
docker build -t web-cli .

Run with Custom Configuration:

# Copy example environment file
cp .env.example .env

# Edit .env with your settings
nano .env

# Start with custom configuration
docker compose up -d

Production Deployment:

# Create .env with production settings
cat > .env << 'EOF'
AUTH_ENABLED=true
AUTH_USERNAME=admin
AUTH_PASSWORD=$(openssl rand -base64 24)
WEBCLI_PORT=7777
EOF

# Start the container
docker compose up -d

# Check credentials
cat .env | grep AUTH_

Docker Run (without Compose):

docker run -d \
  --name web-cli \
  -p 7777:7777 \
  -v web-cli-data:/data \
  -e AUTH_ENABLED=true \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=your-secure-password \
  polinux/web-cli:latest

With TLS/HTTPS:

docker run -d \
  --name web-cli \
  -p 7777:7777 \
  -v web-cli-data:/data \
  -v ./certs:/certs:ro \
  -e WEBCLI_TLS_CERT_PATH=/certs/cert.pem \
  -e WEBCLI_TLS_KEY_PATH=/certs/key.pem \
  -e AUTH_ENABLED=true \
  -e AUTH_USERNAME=admin \
  -e AUTH_PASSWORD=your-secure-password \
  polinux/web-cli:latest

Docker Environment Variables:

Variable	Default	Description
`WEBCLI_PORT`	`7777`	Port to listen on
`WEBCLI_HOST`	`0.0.0.0`	Host to bind to
`WEBCLI_DATABASE_PATH`	`/data/web-cli.db`	Database file path
`WEBCLI_ENCRYPTION_KEY_PATH`	`/data/.encryption_key`	Encryption key file path
`ENCRYPTION_KEY`	(auto-generated)	Base64 encryption key
`AUTH_ENABLED`	`false`	Enable authentication
`AUTH_USERNAME`	`admin`	Basic auth username
`AUTH_PASSWORD`	(none)	Basic auth password
`AUTH_API_TOKEN`	(none)	Bearer token
`WEBCLI_TLS_CERT_PATH`	(none)	TLS certificate path
`WEBCLI_TLS_KEY_PATH`	(none)	TLS private key path
`WEBCLI_REQUIRE_HTTPS`	`false`	Require HTTPS
`CORS_ALLOWED_ORIGINS`	(localhost)	Allowed CORS origins

Volumes:

Path	Description
`/data`	Persistent data (database, encryption key)
`/config`	Configuration files (optional)
`/certs`	TLS certificates (optional)

💻 Development

Backend Development

# Run with hot reload (use air or similar)
go run cmd/web-cli/main.go

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Format code
go fmt ./...

# Lint code
go vet ./...

Frontend Development

cd frontend

# Start dev server with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Build for production
npm run build

Development Workflow

Start backend:
```
go run cmd/web-cli/main.go
```
Start frontend (new terminal):
```
cd frontend && npm run dev
```
Open http://localhost:3000 for hot-reload development

Project Structure

web-cli/
├── cmd/web-cli/           # Application entry point
├── internal/              # Private application code
│   ├── config/            # Configuration management
│   ├── database/          # Database, migrations, encryption
│   ├── executor/          # Command execution (local & remote)
│   │   └── hostkeys.go    # SSH host key verification
│   ├── middleware/        # HTTP middleware (authentication)
│   ├── models/            # Data models
│   ├── repository/        # Data access layer
│   ├── server/            # HTTP server and handlers
│   └── validation/        # Input validation functions
├── frontend/              # React application
│   ├── src/
│   │   ├── components/    # React components
│   │   ├── theme/         # MUI theme configuration
│   │   └── App.jsx        # Main app with routing
│   └── vite.config.js     # Vite configuration
├── build.sh               # Build script (all platforms)
├── manage.sh              # Server management script
├── API.md                 # Complete API documentation
└── go.mod                 # Go dependencies

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow Go best practices and conventions
Write tests for new features
Update documentation as needed
Ensure all tests pass before submitting PR
Keep commits atomic and well-described

📝 License

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

🆘 Support

For issues and questions:

📫 Open an issue on GitHub Issues
📖 Check the API Documentation
🔒 Review Security Improvements for security features

🙏 Acknowledgments

Built with Go - Fast, reliable, and efficient
UI powered by React and Material-UI
Build tool: Vite - Next generation frontend tooling
SSH implementation: golang.org/x/crypto/ssh

Made with ❤️ by Pozgo

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
assets		assets
cmd/web-cli		cmd/web-cli
docs/images		docs/images
frontend		frontend
internal		internal
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
API.md		API.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
manage.sh		manage.sh

License

pozgo/web-cli

Folders and files

Latest commit

History

Repository files navigation

Web CLI

📋 Table of Contents

✨ Features

Core Functionality

Command Execution

Server & SSH Management

Command Templates & History

Environment Variables

Bash Scripts

Security

🛠 Tech Stack

Backend

Frontend

📸 Screenshots

Dashboard

Local Command Execution

Remote Command Execution

Admin Panel - SSH Keys

Admin Panel - Servers

Saved Commands

Command History

📦 Prerequisites

🚀 Installation

Clone the Repository

Install Dependencies

Backend

Frontend

⚡ Quick Start

Build and Run

Using Management Script

📖 Usage

Local Command Execution

Remote Command Execution

Saved Command Templates

📚 API Documentation

🚀 Quick Start

📋 API Endpoints Overview

📖 Complete Documentation

💡 Common Use Cases

⚙️ Configuration

Command-Line Flags

Environment Variables

Configuration File

Configuration Priority

🔒 Security

Authentication (Production Ready)

TLS/HTTPS Support

SSH Host Key Verification

Input Validation

HTTP Security

Database Encryption

Encryption Key Management

Password Security

Database Migrations

🌐 Deployment

Linux Server

systemd Service

Production Deployment Checklist

Docker

💻 Development

Backend Development

Frontend Development

Development Workflow

Project Structure

🤝 Contributing

Development Guidelines

📝 License

🆘 Support

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Packages