apt-ostree/docs/cli-manual-mapping.md

# apt-ostree CLI Manual Mapping

## Overview

This document provides a complete mapping of rpm-ostree CLI commands and options to ensure apt-ostree maintains 100% compatibility. Based on the [rpm-ostree documentation](https://coreos.github.io/rpm-ostree/) and command analysis.

## 🎯 Core Philosophy

apt-ostree aims to be a **hybrid image/package system** that combines:
- **OSTree** as the base image format (atomic, versioned, checksummed)
- **APT** package management (Debian/Ubuntu ecosystem)
- **Client-side package layering** and overrides
- **Transactional updates** with atomic rollback capability

**⚠️ Important**: Most apt-ostree commands require elevated privileges (sudo) as they modify system state, boot configuration, and OSTree deployments. Only read-only operations like `status`, `search`, and help commands can run without privileges.

## 📋 Complete CLI Command Reference

### **Basic Commands**

#### `apt-ostree` (no arguments)
- **Purpose**: Show usage information
- **Expected Output**: Command list and basic help
- **rpm-ostree Equivalent**: `rpm-ostree`
- **Status**: ✅ Implemented

#### `apt-ostree --version`
- **Purpose**: Display version information
- **Expected Output**: Version, copyright, license
- **rpm-ostree Equivalent**: `rpm-ostree --version`
- **Status**: ✅ Implemented

#### `apt-ostree --help` / `apt-ostree -h`
- **Purpose**: Display help information
- **Expected Output**: Full command reference
- **rpm-ostree Equivalent**: `rpm-ostree --help`
- **Status**: ✅ Implemented

#### `apt-ostree -q` / `apt-ostree --quiet`
- **Purpose**: Reduce output verbosity
- **Expected Output**: Minimal output
- **rpm-ostree Equivalent**: `rpm-ostree -q`
- **Status**: ✅ Implemented

### **System Status Commands**

#### `apt-ostree status`
- **Purpose**: Show current system status
- **Expected Output**: Deployment information, boot status
- **rpm-ostree Equivalent**: `rpm-ostree status`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟢 No privileges required (read-only)
- **Options**:
  - `--json` - JSON output format
  - `--peer` - Force peer-to-peer connection
  - `--sysroot=SYSROOT` - Use specific system root

#### `apt-ostree status --help`
- **Purpose**: Show status command help
- **Expected Output**: Status command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree status --help`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟢 No privileges required (read-only)

### **Package Management Commands**

#### `apt-ostree install <package>`
- **Purpose**: Install package (atomic overlay)
- **Expected Output**: Installation progress and result
- **rpm-ostree Equivalent**: `rpm-ostree install <package>`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--allow-inactive` - Allow inactive packages
  - `--apply-live` - Apply changes immediately
  - `--cache-only` - Use only cached packages
  - `--force-replacefiles` - Force file replacement
  - `--idempotent` - Skip if already installed
  - `--reboot` - Reboot after installation
  - `--dry-run` - Show what would be done

#### `apt-ostree install --help`
- **Purpose**: Show install command help
- **Expected Output**: Install command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree install --help`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟢 No privileges required (read-only)

#### `apt-ostree uninstall <package>`
- **Purpose**: Remove package (atomic overlay)
- **Expected Output**: Removal progress and result
- **rpm-ostree Equivalent**: `rpm-ostree uninstall <package>`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after removal
  - `--dry-run` - Show what would be done

#### `apt-ostree uninstall --help`
- **Purpose**: Show uninstall command help
- **Expected Output**: Uninstall command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree uninstall --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **System Update Commands**

#### `apt-ostree upgrade`
- **Purpose**: Perform system upgrade (atomic)
- **Expected Output**: Upgrade progress and result
- **rpm-ostree Equivalent**: `rpm-ostree upgrade`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--allow-downgrade` - Allow version downgrades
  - `--cache-only` - Use only cached packages
  - `--check` - Check for available updates
  - `--download-only` - Download without installing
  - `--reboot` - Reboot after upgrade
  - `--dry-run` - Show what would be done

#### `apt-ostree upgrade --help`
- **Purpose**: Show upgrade command help
- **Expected Output**: Upgrade command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree upgrade --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree rollback`
- **Purpose**: Rollback to previous deployment
- **Expected Output**: Rollback progress and result
- **rpm-ostree Equivalent**: `rpm-ostree rollback`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after rollback
  - `--dry-run` - Show what would be done

#### `apt-ostree rollback --help`
- **Purpose**: Show rollback command help
- **Expected Output**: Rollback command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree rollback --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Package Search Commands**

#### `apt-ostree search <query>`
- **Purpose**: Search for available packages
- **Expected Output**: Package list matching query
- **rpm-ostree Equivalent**: `rpm-ostree search <query>`
- **Status**: ✅ Implemented (basic functionality)
- **Privileges**: 🟢 No privileges required (read-only)
- **Options**:
  - `--repo=REPO` - Search specific repository
  - `--show-duplicates` - Show duplicate packages
  - `--quiet` - Minimal output

#### `apt-ostree search --help`
- **Purpose**: Show search command help
- **Expected Output**: Search command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree search --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Deployment Commands**

#### `apt-ostree deploy <commit>`
- **Purpose**: Deploy specific commit
- **Expected Output**: Deployment progress and result
- **rpm-ostree Equivalent**: `rpm-ostree deploy <commit>`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after deployment
  - `--dry-run` - Show what would be done

#### `apt-ostree deploy --help`
- **Purpose**: Show deploy command help
- **Expected Output**: Deploy command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree deploy --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree rebase <target>`
- **Purpose**: Switch to different tree/branch
- **Expected Output**: Rebase progress and result
- **rpm-ostree Equivalent**: `rpm-ostree rebase <target>`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after rebase
  - `--dry-run` - Show what would be done

#### `apt-ostree rebase --help`
- **Purpose**: Show rebase command help
- **Expected Output**: Rebase command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree rebase --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Transaction Management Commands**

#### `apt-ostree cancel`
- **Purpose**: Cancel active transaction
- **Expected Output**: Transaction cancellation result
- **rpm-ostree Equivalent**: `rpm-ostree cancel`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--peer` - Force peer-to-peer connection
  - `--sysroot=SYSROOT` - Use specific system root

#### `apt-ostree cancel --help`
- **Purpose**: Show cancel command help
- **Expected Output**: Cancel command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree cancel --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree cleanup`
- **Purpose**: Clear cached/pending data
- **Expected Output**: Cleanup progress and result
- **rpm-ostree Equivalent**: `rpm-ostree cleanup`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--base` - Clean base deployments
  - `--rollback` - Clean rollback deployments

#### `apt-ostree cleanup --help`
- **Purpose**: Show cleanup command help
- **Expected Output**: Cleanup command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree cleanup --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Live Update Commands**

#### `apt-ostree apply-live`
- **Purpose**: Apply pending deployment changes
- **Expected Output**: Live update progress and result
- **rpm-ostree Equivalent**: `rpm-ostree apply-live`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--target` - Apply specific target
  - `--dry-run` - Show what would be done

#### `apt-ostree apply-live --help`
- **Purpose**: Show apply-live command help
- **Expected Output**: Apply-live command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree apply-live --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Finalization Commands**

#### `apt-ostree finalize-deployment`
- **Purpose**: Finalize staged deployment
- **Expected Output**: Finalization result
- **rpm-ostree Equivalent**: `rpm-ostree finalize-deployment`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after finalization

#### `apt-ostree finalize-deployment --help`
- **Purpose**: Show finalize-deployment command help
- **Expected Output**: Finalize-deployment command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree finalize-deployment --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Configuration Commands**

#### `apt-ostree reload`
- **Purpose**: Reload configuration
- **Expected Output**: Reload result
- **rpm-ostree Equivalent**: `rpm-ostree reload`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)

#### `apt-ostree reload --help`
- **Purpose**: Show reload command help
- **Expected Output**: Reload command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree reload --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree reset`
- **Purpose**: Remove all mutations
- **Expected Output**: Reset progress and result
- **rpm-ostree Equivalent**: `rpm-ostree reset`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Options**:
  - `--reboot` - Reboot after reset
  - `--dry-run` - Show what would be done

#### `apt-ostree reset --help`
- **Purpose**: Show reset command help
- **Expected Output**: Reset command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree reset --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Metadata Commands**

#### `apt-ostree refresh-md`
- **Purpose**: Generate repository metadata
- **Expected Output**: Metadata generation result
- **rpm-ostree Equivalent**: `rpm-ostree refresh-md`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)

#### `apt-ostree refresh-md --help`
- **Purpose**: Show refresh-md command help
- **Expected Output**: Refresh-md command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree refresh-md --help`
- **Status**: 🔧 Placeholder (needs implementation)

### **Subcommand Groups**

#### `apt-ostree compose`
- **Purpose**: Compose commands
- **Expected Output**: Compose subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree compose`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `start` - Start compose operation
  - `status` - Show compose status
  - `cancel` - Cancel compose operation

#### `apt-ostree compose --help`
- **Purpose**: Show compose command help
- **Expected Output**: Compose command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree compose --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree db`
- **Purpose**: Database commands
- **Expected Output**: Database subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree db`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟢 No privileges required (read-only)
- **Subcommands**:
  - `list` - List database contents
  - `diff` - Show database differences

#### `apt-ostree db --help`
- **Purpose**: Show db command help
- **Expected Output**: Db command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree db --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree initramfs`
- **Purpose**: Initramfs commands
- **Expected Output**: Initramfs subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree initramfs`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `enable` - Enable initramfs regeneration
  - `disable` - Disable initramfs regeneration

#### `apt-ostree initramfs --help`
- **Purpose**: Show initramfs command help
- **Expected Output**: Initramfs command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree initramfs --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree initramfs-etc`
- **Purpose**: Initramfs-etc commands
- **Expected Output**: Initramfs-etc subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree initramfs-etc`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `add` - Add files to initramfs
  - `remove` - Remove files from initramfs

#### `apt-ostree initramfs-etc --help`
- **Purpose**: Show initramfs-etc command help
- **Expected Output**: Initramfs-etc command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree initramfs-etc --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree kargs`
- **Purpose**: Kernel arguments commands
- **Expected Output**: Kargs subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree kargs`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `get` - Get kernel arguments
  - `set` - Set kernel arguments
  - `delete` - Delete kernel arguments

#### `apt-ostree kargs --help`
- **Purpose**: Show kargs command help
- **Expected Output**: Kargs command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree kargs --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree override`
- **Purpose**: Override commands
- **Expected Output**: Override subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree override`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `add` - Add package override
  - `remove` - Remove package override
  - `reset` - Reset all overrides
  - `replace` - Replace package with URL

#### `apt-ostree override --help`
- **Purpose**: Show override command help
- **Expected Output**: Override command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree override --help`
- **Status**: 🔧 Placeholder (needs implementation)

#### `apt-ostree usroverlay`
- **Purpose**: USR overlay commands
- **Expected Output**: Usroverlay subcommand list
- **rpm-ostree Equivalent**: `rpm-ostree usroverlay`
- **Status**: 🔧 Placeholder (needs implementation)
- **Privileges**: 🟡 Elevated privileges required (sudo)
- **Subcommands**:
  - `apply` - Apply transient overlay
  - `remove` - Remove transient overlay

#### `apt-ostree usroverlay --help`
- **Purpose**: Show usroverlay command help
- **Expected Output**: Usroverlay command options and usage
- **rpm-ostree Equivalent**: `rpm-ostree usroverlay --help`
- **Status**: 🔧 Placeholder (needs implementation)

## 🔧 Global Options

### **System Options**
- `--sysroot=SYSROOT` - Use specific system root (default: /)
- `--peer` - Force peer-to-peer connection instead of system message bus

### **Output Options**
- `--json` - JSON output format
- `--quiet` / `-q` - Reduce output verbosity
- `--verbose` / `-v` - Increase output verbosity

### **Debug Options**
- `--debug` - Enable debug output
- `--trace` - Enable trace output

## 🔐 Privilege Requirements

### **🟢 No Privileges Required (Read-Only)**
- `--version`, `--help`, `-h` - Basic information
- `status` - System status (read-only)
- `search <query>` - Package search
- `db list` - Database listing
- `db diff` - Database differences

### **🟡 Elevated Privileges Required (sudo)**
- `install <package>` - Package installation (modifies system)
- `uninstall <package>` - Package removal (modifies system)
- `upgrade` - System upgrade (modifies system)
- `rollback` - System rollback (modifies boot configuration)
- `deploy <commit>` - Deploy specific commit (modifies system)
- `rebase <target>` - Switch tree/branch (modifies system)
- `apply-live` - Apply pending changes (modifies running system)
- `finalize-deployment` - Finalize deployment (modifies system)
- `cancel` - Cancel transaction (modifies system state)
- `cleanup` - Clear cached data (modifies system)
- `reload` - Reload configuration (modifies system)
- `reset` - Remove mutations (modifies system)
- `refresh-md` - Generate metadata (modifies repository data)
- `compose` - Compose operations (modifies system)
- `initramfs` - Initramfs management (modifies boot)
- `initramfs-etc` - Initramfs file management (modifies boot)
- `kargs` - Kernel arguments (modifies boot configuration)
- `override` - Package overrides (modifies system)
- `usroverlay` - USR overlay (modifies filesystem)

### **🔴 Root Privileges Required**
- All commands that modify the system state
- Commands that interact with OSTree admin operations
- Commands that modify bootloader configuration
- Commands that create/delete deployments

## 📖 Complete Help System Mapping

### **🔍 Main Help Commands**

#### `apt-ostree --help` / `apt-ostree -h`
- **Purpose**: Show main help and command list
- **Expected Output**: Complete command reference
- **rpm-ostree Equivalent**: `rpm-ostree --help`
- **Status**: ✅ Implemented
- **Privileges**: 🟢 No privileges required

#### `apt-ostree help`
- **Purpose**: Show main help (subcommand version)
- **Expected Output**: Same as `--help`
- **rpm-ostree Equivalent**: `rpm-ostree help`
- **Status**: ✅ Implemented
- **Privileges**: 🟢 No privileges required

### **📚 Command-Specific Help**

#### **System Status Commands**
- `apt-ostree status --help` - Status command options
- `apt-ostree status -h` - Short help for status

#### **Package Management Commands**
- `apt-ostree install --help` - Install command options
- `apt-ostree install -h` - Short help for install
- `apt-ostree uninstall --help` - Uninstall command options
- `apt-ostree uninstall -h` - Short help for uninstall

#### **System Update Commands**
- `apt-ostree upgrade --help` - Upgrade command options
- `apt-ostree upgrade -h` - Short help for upgrade
- `apt-ostree rollback --help` - Rollback command options
- `apt-ostree rollback -h` - Short help for rollback

#### **Package Search Commands**
- `apt-ostree search --help` - Search command options
- `apt-ostree search -h` - Short help for search

#### **Deployment Commands**
- `apt-ostree deploy --help` - Deploy command options
- `apt-ostree deploy -h` - Short help for deploy
- `apt-ostree rebase --help` - Rebase command options
- `apt-ostree rebase -h` - Short help for rebase

#### **Transaction Management Commands**
- `apt-ostree cancel --help` - Cancel command options
- `apt-ostree cancel -h` - Short help for cancel
- `apt-ostree cleanup --help` - Cleanup command options
- `apt-ostree cleanup -h` - Short help for cleanup

#### **Live Update Commands**
- `apt-ostree apply-live --help` - Apply-live command options
- `apt-ostree apply-live -h` - Short help for apply-live

#### **Finalization Commands**
- `apt-ostree finalize-deployment --help` - Finalize-deployment options
- `apt-ostree finalize-deployment -h` - Short help for finalize-deployment

#### **Configuration Commands**
- `apt-ostree reload --help` - Reload command options
- `apt-ostree reload -h` - Short help for reload
- `apt-ostree reset --help` - Reset command options
- `apt-ostree reset -h` - Short help for reset

#### **Metadata Commands**
- `apt-ostree refresh-md --help` - Refresh-md command options
- `apt-ostree refresh-md -h` - Short help for refresh-md

### **🔧 Subcommand Group Help**

#### **Compose Commands**
- `apt-ostree compose --help` - Compose subcommand list
- `apt-ostree compose -h` - Short help for compose
- `apt-ostree compose start --help` - Start compose options
- `apt-ostree compose status --help` - Status compose options
- `apt-ostree compose cancel --help` - Cancel compose options

#### **Database Commands**
- `apt-ostree db --help` - Database subcommand list
- `apt-ostree db -h` - Short help for db
- `apt-ostree db list --help` - List database options
- `apt-ostree db diff --help` - Diff database options

#### **Initramfs Commands**
- `apt-ostree initramfs --help` - Initramfs subcommand list
- `apt-ostree initramfs -h` - Short help for initramfs
- `apt-ostree initramfs enable --help` - Enable initramfs options
- `apt-ostree initramfs disable --help` - Disable initramfs options

#### **Initramfs-etc Commands**
- `apt-ostree initramfs-etc --help` - Initramfs-etc subcommand list
- `apt-ostree initramfs-etc -h` - Short help for initramfs-etc
- `apt-ostree initramfs-etc add --help` - Add initramfs-etc options
- `apt-ostree initramfs-etc remove --help` - Remove initramfs-etc options

#### **Kernel Arguments Commands**
- `apt-ostree kargs --help` - Kargs subcommand list
- `apt-ostree kargs -h` - Short help for kargs
- `apt-ostree kargs get --help` - Get kargs options
- `apt-ostree kargs set --help` - Set kargs options
- `apt-ostree kargs delete --help` - Delete kargs options

#### **Override Commands**
- `apt-ostree override --help` - Override subcommand list
- `apt-ostree override -h` - Short help for override
- `apt-ostree override add --help` - Add override options
- `apt-ostree override remove --help` - Remove override options
- `apt-ostree override reset --help` - Reset override options
- `apt-ostree override replace --help` - Replace override options

#### **USR Overlay Commands**
- `apt-ostree usroverlay --help` - Usroverlay subcommand list
- `apt-ostree usroverlay -h` - Short help for usroverlay
- `apt-ostree usroverlay apply --help` - Apply usroverlay options
- `apt-ostree usroverlay remove --help` - Remove usroverlay options

### **⚙️ Option-Specific Help**

#### **Global Options Help**
- `apt-ostree --sysroot=/ --help` - Help with sysroot option
- `apt-ostree --peer --help` - Help with peer option
- `apt-ostree --version --help` - Help with version option
- `apt-ostree -q --help` - Help with quiet option

#### **Command-Specific Options Help**
- `apt-ostree status --json --help` - Help with JSON output
- `apt-ostree status --peer --help` - Help with peer connection
- `apt-ostree install --reboot --help` - Help with reboot option
- `apt-ostree install --dry-run --help` - Help with dry-run option
- `apt-ostree upgrade --check --help` - Help with check option
- `apt-ostree rollback --dry-run --help` - Help with dry-run option

### **📋 Help Output Structure**

#### **Standard Help Format**
```
Usage:
  apt-ostree COMMAND [OPTION…]

Command description

Help Options:
  -h, --help            Show help options

Application Options:
  --sysroot=SYSROOT     Use system root SYSROOT (default: /)
  --peer                Force peer-to-peer connection
  --version             Print version information and exit
  -q, --quiet           Avoid printing most informational messages
```

#### **Subcommand Help Format**
```
Usage:
  apt-ostree COMMAND SUBCOMMAND [OPTION…]

Subcommand description

Help Options:
  -h, --help            Show help options

Application Options:
  --sysroot=SYSROOT     Use system root SYSROOT (default: /)
  --peer                Force peer-to-peer connection
  --version             Print version information and exit
  -q, --quiet           Avoid printing most informational messages
```

### **🎯 Help Implementation Status**

#### **✅ Help Commands Implemented**
- Main help (`--help`, `-h`, `help`)
- Basic command structure

#### **🔧 Help Commands to Implement**
- Command-specific help (`command --help`)
- Subcommand help (`command subcommand --help`)
- Option-specific help (`--option --help`)
- Help output formatting
- Help content generation

#### **📚 Help Content to Create**
- Command descriptions
- Option explanations
- Usage examples
- Error message help
- Troubleshooting tips

## 📊 Implementation Status

### **✅ Fully Implemented**
- Basic command structure
- Version and help flags
- Search functionality (basic)
- Command-line argument parsing

### **🔧 Placeholder Implemented**
- All major commands have placeholder functions
- Error handling structure in place
- Logging framework ready

### **❌ Not Yet Implemented**
- OSTree integration
- APT package management
- Transaction handling
- System operations
- Configuration management

### **🔐 Privilege Analysis Complete**
- **🟢 Read-Only Commands**: 5 commands (no privileges needed)
- **🟡 Elevated Privileges**: 20+ commands (sudo required)
- **🔴 Root Privileges**: All system-modifying operations

### **📖 Help System Mapping Complete**
- **🔍 Main Help**: 3 commands (`--help`, `-h`, `help`)
- **📚 Command Help**: 25+ commands with `--help` support
- **🔧 Subcommand Help**: 15+ subcommands with help
- **⚙️ Option Help**: Global and command-specific options
- **📋 Help Formats**: Standard and subcommand formats defined

## 🚀 Next Implementation Steps

### **Phase 1: Core Infrastructure**
1. Implement OSTree manager
2. Implement APT package manager
3. Add transaction handling

### **Phase 2: Command Implementation**
1. Implement status command
2. Implement install/uninstall commands
3. Implement upgrade/rollback commands

### **Phase 3: Advanced Features**
1. Implement override system
2. Implement initramfs management
3. Implement kernel argument management

### **Phase 4: Integration & Testing**
1. End-to-end testing
2. Performance optimization
3. Documentation completion

## 📚 Reference Materials

- [rpm-ostree Official Documentation](https://coreos.github.io/rpm-ostree/)
- [rpm-ostree GitHub Repository](https://github.com/coreos/rpm-ostree)
- [OSTree Documentation](https://ostreedev.github.io/ostree/)
- [APT Package Management](https://wiki.debian.org/Apt)

---

*This CLI manual mapping ensures apt-ostree maintains 100% compatibility with rpm-ostree while adapting to the Debian/Ubuntu ecosystem.*