atlas/docs/TUI.md

# Terminal User Interface (TUI)

## Overview

AtlasOS provides a Terminal User Interface (TUI) for managing the storage system from the command line. The TUI provides an interactive menu-driven interface that connects to the Atlas API.

## Features

- **Interactive Menus**: Navigate through system features with simple menus
- **Authentication**: Secure login to the API
- **ZFS Management**: View and manage pools, datasets, and ZVOLs
- **Storage Services**: Manage SMB shares, NFS exports, and iSCSI targets
- **Snapshot Management**: Create snapshots and manage policies
- **System Information**: View system health and diagnostics
- **Backup & Restore**: Manage configuration backups

## Installation

Build the TUI binary:

```bash
go build ./cmd/atlas-tui
```

Or use the Makefile:

```bash
make build
```

This creates the `atlas-tui` binary.

## Configuration

### API URL

Set the API URL via environment variable:

```bash
export ATLAS_API_URL=http://localhost:8080
./atlas-tui
```

Default: `http://localhost:8080`

## Usage

### Starting the TUI

```bash
./atlas-tui
```

### Authentication

On first run, you'll be prompted to login:

```
=== AtlasOS Login ===
Username: admin
Password: ****
Login successful!
```

### Main Menu

```
=== AtlasOS Terminal Interface ===
1. ZFS Management
2. Storage Services
3. Snapshots
4. System Information
5. Backup & Restore
0. Exit
```

## Menu Options

### 1. ZFS Management

**Sub-menu:**
- List Pools
- List Datasets
- List ZVOLs
- List Disks

**Example - List Pools:**
```
=== ZFS Pools ===
1. tank
   Size: 10TB
   Used: 2TB
```

### 2. Storage Services

**Sub-menu:**
- SMB Shares
- NFS Exports
- iSCSI Targets

**SMB Shares:**
- List Shares
- Create Share

**Example - Create SMB Share:**
```
Share name: data-share
Dataset: tank/data
Path (optional, press Enter to auto-detect): 
Description (optional): Main data share
SMB share created successfully!
Share: data-share
```

**NFS Exports:**
- List Exports
- Create Export

**Example - Create NFS Export:**
```
Dataset: tank/data
Path (optional, press Enter to auto-detect): 
Clients (comma-separated, e.g., 192.168.1.0/24,*): 192.168.1.0/24
NFS export created successfully!
Export: /tank/data
```

**iSCSI Targets:**
- List Targets
- Create Target

**Example - Create iSCSI Target:**
```
IQN (e.g., iqn.2024-12.com.atlas:target1): iqn.2024-12.com.atlas:target1
iSCSI target created successfully!
Target: iqn.2024-12.com.atlas:target1
```

### 3. Snapshots

**Sub-menu:**
- List Snapshots
- Create Snapshot
- List Snapshot Policies

**Example - Create Snapshot:**
```
Dataset name: tank/data
Snapshot name: backup-2024-12-20
Snapshot created successfully!
Snapshot: tank/data@backup-2024-12-20
```

### 4. System Information

**Sub-menu:**
- System Info
- Health Check
- Dashboard

**System Info:**
```
=== System Information ===
Version: v0.1.0-dev
Uptime: 3600 seconds
Go Version: go1.21.0
Goroutines: 15

Services:
  smb: running
  nfs: running
  iscsi: stopped
```

**Health Check:**
```
=== Health Check ===
Status: healthy

Component Checks:
  zfs: healthy
  database: healthy
  smb: healthy
  nfs: healthy
  iscsi: stopped
```

**Dashboard:**
```
=== Dashboard ===
Pools: 2
Datasets: 10
SMB Shares: 5
NFS Exports: 3
iSCSI Targets: 2
```

### 5. Backup & Restore

**Sub-menu:**
- List Backups
- Create Backup
- Restore Backup

**Example - Create Backup:**
```
Description (optional): Weekly backup
Backup created successfully!
Backup ID: backup-1703123456
```

**Example - Restore Backup:**
```
=== Backups ===
1. backup-1703123456
   Created: 2024-12-20T10:30:56Z
   Description: Weekly backup

Backup ID: backup-1703123456
Restore backup? This will overwrite current configuration. (yes/no): yes
Backup restored successfully!
```

## Navigation

- **Select Option**: Enter the number or letter corresponding to the menu option
- **Back**: Enter `0` to go back to the previous menu
- **Exit**: Enter `0`, `q`, or `exit` to quit the application
- **Interrupt**: Press `Ctrl+C` for graceful shutdown

## Keyboard Shortcuts

- `Ctrl+C`: Graceful shutdown
- `0`: Back/Exit
- `q`: Exit
- `exit`: Exit

## Examples

### Complete Workflow

```bash
# Start TUI
./atlas-tui

# Login
Username: admin
Password: admin

# Navigate to ZFS Management
Select option: 1

# List pools
Select option: 1

# Go back
Select option: 0

# Create SMB share
Select option: 2
Select option: 1
Select option: 2
Share name: myshare
Dataset: tank/data
...

# Exit
Select option: 0
Select option: 0
```

## API Client

The TUI uses an HTTP client to communicate with the Atlas API:

- **Authentication**: JWT token-based authentication
- **Error Handling**: Clear error messages for API failures
- **Timeout**: 30-second timeout for requests

## Error Handling

The TUI handles errors gracefully:

- **Connection Errors**: Clear messages when API is unreachable
- **Authentication Errors**: Prompts for re-authentication
- **API Errors**: Displays error messages from API responses
- **Invalid Input**: Validates user input before sending requests

## Configuration File

Future enhancement: Support for configuration file:

```yaml
api_url: http://localhost:8080
username: admin
# Token can be stored (with appropriate security)
```

## Security Considerations

1. **Password Input**: Currently visible (future: hidden input)
2. **Token Storage**: Token stored in memory only
3. **HTTPS**: Use HTTPS for production API URLs
4. **Credentials**: Never log credentials

## Limitations

- **Password Visibility**: Passwords are currently visible during input
- **No Token Persistence**: Must login on each TUI start
- **Basic Interface**: Text-based menus (not a full TUI library)
- **Limited Error Recovery**: Some errors require restart

## Future Enhancements

1. **Hidden Password Input**: Use library to hide password input
2. **Token Persistence**: Store token securely for session persistence
3. **Advanced TUI**: Use Bubble Tea or similar for rich interface
4. **Command Mode**: Support command-line arguments for non-interactive use
5. **Configuration File**: Support for config file
6. **Auto-completion**: Tab completion for commands
7. **History**: Command history support
8. **Color Output**: Colored output for better readability
9. **Progress Indicators**: Show progress for long operations
10. **Batch Operations**: Support for batch operations

## Troubleshooting

### Connection Errors

```
Error: request failed: dial tcp 127.0.0.1:8080: connect: connection refused
```

**Solution**: Ensure the API server is running:
```bash
./atlas-api
```

### Authentication Errors

```
Error: login failed: invalid credentials
```

**Solution**: Check username and password. Default credentials:
- Username: `admin`
- Password: `admin`

### API URL Configuration

If API is on a different host/port:

```bash
export ATLAS_API_URL=http://192.168.1.100:8080
./atlas-tui
```

## Comparison with Web GUI

| Feature | TUI | Web GUI |
|---------|-----|---------|
| **Access** | Local console | Browser |
| **Setup** | No browser needed | Requires browser |
| **Network** | Works offline (local) | Requires network |
| **Rich UI** | Text-based | HTML/CSS/JS |
| **Initial Setup** | Ideal for setup | Better for daily use |
| **Maintenance** | Good for maintenance | Good for monitoring |

## Best Practices

1. **Use TUI for Initial Setup**: TUI is ideal for initial system configuration
2. **Use Web GUI for Daily Operations**: Web GUI provides better visualization
3. **Keep API Running**: TUI requires the API server to be running
4. **Secure Credentials**: Don't share credentials or tokens
5. **Use HTTPS in Production**: Always use HTTPS for production API URLs