GoSh is a modular, interactive command-line interface built in Go. It provides a containerized environment for secure command execution, system monitoring, and file management.
- Robust Command Engine: Utilizes
urfave/cli/v3 for sophisticated argument parsing and flag management.
- Enhanced Security: Path traversal guards, directory traversal checks, and confirmation prompts for destructive actions.
- Portability: Works natively or containerized with Docker.
- Interactive Experience: Integrated command scanning provides a fluid terminal interaction.
- System Monitoring: Built-in tools for monitoring CPU, memory, disk usage, and process management.
- Network Utilities: Integrated network diagnostic tools including ping functionality.
- Archive Management: Support for creating and extracting ZIP archives with security checks.
- Security Scanned: Code undergoes gosec security analysis.
gosh/
├── cmd/gosh/main.go # Entry point
├── internal/handlers/ # Command implementations
│ ├── commands.go # Command aggregator
│ ├── shell.go # Shell utilities (ls, cd, pwd, mkdir, cp, mv, etc.)
│ ├── system.go # System monitoring (sys, mu, du, ps, kill, etc.)
│ ├── text.go # Text processing (grep, head, tail)
│ ├── network.go # Networking (ping)
│ └── storage.go # Archives (zip, unzip)
├── Makefile # Build automation
├── Dockerfile # Container definition
└── compose.yaml # Docker Compose
| Component |
Description |
cmd/gosh/main.go |
Entry point, sets up urfave/cli and command loop |
internal/handlers/ |
All command implementations |
The core engine is built on urfave/cli/v3. It maps user input to specific handler functions in internal/handlers/. New commands can be added by implementing a handler function and registering it in commands.go.
- Go: Version 1.25 or higher
- Docker: Optional, for containerized execution
- Clone the repository:
git clone https://github.com/Masralai/gosh
cd gosh
- Build:
make build
# or
go build -o gosh ./cmd/gosh
- Run:
docker compose up --build
make build # Builds binary to ./gosh
make test # Runs tests with race detector
make lint # Runs linter
make vet # Runs go vet
make clean # Removes binary
# Build binary
go build -o gosh ./cmd/gosh
# Run tests
go test -race ./...
# Lint
golangci-lint run ./...
# Vet
go vet ./...
Run tests with race detection:
make test
# or
go test -race ./...
| Command |
Description |
Flags |
ls |
List directory contents |
-a (hidden), -R (recursive), -S (size) |
cd |
Change directory |
|
pwd |
Print working directory |
|
mkdir |
Create directory |
|
rm |
Remove files/directories |
-rf (recursive) |
touch |
Create empty file |
|
mv |
Move/rename |
|
cp |
Copy file |
|
cat |
Display file contents |
-n (line numbers), -b (non-blank), -s (squeeze) |
info |
File information |
|
dir |
List directory |
|
| Command |
Description |
ps |
Process status |
sys |
System information |
mu |
Memory usage |
du |
Disk usage |
ut |
Uptime |
| Command |
Description |
Flags |
grep |
Search text using regex |
-f (ignore case), -r (recursive), -v (invert) |
head |
Display first lines |
-n (count) |
tail |
Display last lines |
-n (count) |
| Command |
Description |
ping |
Ping a host |
| Command |
Description |
zip |
Create ZIP archive |
unzip |
Extract ZIP archive |
| Command |
Description |
Flags |
echo |
Display text |
-n (no newline), -e (escapes) |
boom |
Explosive entrance |
|
exit |
Exit shell |
|
Contributions are welcome! Please submit a PR or open an issue.
Distributed under the MIT License. See LICENSE for more information.
