apt-ostree/.notes/cli/apt-ostree.md

apt-ostree CLI Analysis

Executive Summary

apt-ostree provides a 100% compatible command-line interface with rpm-ostree, serving as the primary user interface for the Debian/Ubuntu hybrid image/package system. The CLI maintains identical user experience while adapting the underlying functionality to the APT/DEB ecosystem.

CLI Architecture

Command Structure

apt-ostree follows the exact same hierarchical command structure as rpm-ostree:

apt-ostree [GLOBAL_OPTIONS] COMMAND [COMMAND_OPTIONS] [ARGUMENTS]

Global Options

• --version: Show version information
• --help: Show help information
• --verbose: Enable verbose output
• --quiet: Suppress output
• --json: Output in JSON format
• --sysroot=PATH: Specify system root path

100% Compatibility

All commands, options, and output formats are identical to rpm-ostree, ensuring:

• Identical User Experience: Same commands and options
• Familiar Interface: No learning curve for rpm-ostree users
• Consistent Behavior: Same behavior across systems
• Easy Migration: Seamless migration from rpm-ostree

Core Commands (21/21 - 100% Complete)

1. Status Command

Purpose: Display system status and deployment information

Usage:

apt-ostree status [OPTIONS]

Options:

• --json: Output in JSON format
• --booted: Show only booted deployment
• --pending: Show only pending deployment

Output Format:

State: idle
Deployments:
* ostree://debian:debian/amd64/ostree
                   Version: 12.20231201.0 (2023-12-01 12:34:56)
                BaseCommit: abc123def456...
              GPGSignature: Valid signature by 1234567890ABCDEF
           LayeredPackages: vim git

  ostree://debian:debian/amd64/ostree
                   Version: 12.20231115.0 (2023-11-15 10:20:30)
                BaseCommit: def456ghi789...
              GPGSignature: Valid signature by 1234567890ABCDEF
           LayeredPackages: vim

Implementation:

• Queries OSTree sysroot for deployment information
• Displays current and available deployments
• Shows layered packages and version information
• Indicates booted and pending deployments
• Uses APT database for package information

2. Upgrade Command

Purpose: Upgrade system to latest version

Usage:

apt-ostree upgrade [OPTIONS]

Options:

• --check: Check for updates without upgrading
• --download-only: Download updates without installing
• --reboot: Automatically reboot after upgrade
• --allow-downgrade: Allow downgrading packages
• --unchanged-exit-77: Exit with 77 if no changes

Execution Flow:

1. Check for available updates via APT
2. Download new packages via APT
3. Create new deployment
4. Install updates
5. Update boot configuration
6. Optionally reboot

Implementation:

• Uses libapt-pkg to check for updates
• Downloads packages via APT
• Creates new OSTree commit with updates
• Manages deployment switching
• Handles rollback on failure

3. Rollback Command

Purpose: Rollback to previous deployment

Usage:

apt-ostree rollback [OPTIONS]

Options:

• --reboot: Automatically reboot after rollback
• --not-as-default: Don't set as default boot option

Execution Flow:

1. Identify previous deployment
2. Switch to previous deployment
3. Update boot configuration
4. Optionally reboot

Implementation:

• Queries OSTree for available deployments
• Switches to previous deployment
• Updates GRUB/systemd-boot configuration
• Manages boot order

4. Deploy Command

Purpose: Deploy specific version or commit

Usage:

apt-ostree deploy [OPTIONS] [REF]

Options:

• --reboot: Automatically reboot after deployment
• --not-as-default: Don't set as default boot option
• --os=OSNAME: Specify operating system name

Examples:

# Deploy specific version
apt-ostree deploy debian:debian/amd64/ostree/12.20231201.0

# Deploy specific commit
apt-ostree deploy abc123def456...

# Deploy with reboot
apt-ostree deploy --reboot debian:debian/amd64/ostree/12.20231201.0

Implementation:

• Validates deployment reference
• Downloads deployment if needed
• Switches to specified deployment
• Updates boot configuration

5. Install Command

Purpose: Install packages as layers

Usage:

apt-ostree install [OPTIONS] PACKAGES...

Options:

• --reboot: Automatically reboot after installation
• --allow-inactive: Allow installing on inactive deployment
• --idempotent: Don't error if packages already installed

Examples:

# Install single package
apt-ostree install vim

# Install multiple packages
apt-ostree install vim git build-essential

# Install with reboot
apt-ostree install --reboot firefox

Execution Flow:

1. Resolve package dependencies via APT
2. Download packages via APT
3. Create new deployment with packages
4. Install packages in new deployment
5. Update boot configuration
6. Optionally reboot

Implementation:

• Uses libapt-pkg for dependency resolution
• Downloads packages via APT
• Creates new OSTree commit with packages
• Manages package layering
• Handles conflicts and rollback

6. Uninstall Command

Purpose: Remove layered packages

Usage:

apt-ostree uninstall [OPTIONS] PACKAGES...

Options:

• --reboot: Automatically reboot after uninstallation
• --idempotent: Don't error if packages not installed

Examples:

# Remove single package
apt-ostree uninstall vim

# Remove multiple packages
apt-ostree uninstall vim git

# Remove with reboot
apt-ostree uninstall --reboot firefox

Execution Flow:

1. Check if packages are installed
2. Create new deployment without packages
3. Remove packages from new deployment
4. Update boot configuration
5. Optionally reboot

Implementation:

• Validates package installation status
• Creates new deployment without packages
• Manages package removal
• Handles dependencies and conflicts

7. Override Command

Purpose: Manage package overrides

Usage:

apt-ostree override [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• replace: Replace package with different version
• remove: Remove package from base
• reset: Reset package to base version
• list: List current overrides

Examples:

# Replace package
apt-ostree override replace kernel /path/to/custom-kernel.deb

# Remove package from base
apt-ostree override remove package-name

# Reset package
apt-ostree override reset package-name

# List overrides
apt-ostree override list

Implementation:

• Manages package override state
• Handles package replacement
• Tracks override history
• Manages base package modifications

8. Rebase Command

Purpose: Switch to different base image

Usage:

apt-ostree rebase [OPTIONS] [REF]

Options:

• --reboot: Automatically reboot after rebase
• --os=OSNAME: Specify operating system name

Examples:

# Rebase to different version
apt-ostree rebase debian:debian/amd64/ostree/13

# Rebase to different OS
apt-ostree rebase --os=debian debian:debian/amd64/ostree/13

Execution Flow:

1. Download new base image
2. Merge user packages to new base
3. Create new deployment
4. Update boot configuration
5. Optionally reboot

Implementation:

• Downloads new base image
• Preserves user packages
• Creates new deployment
• Manages package compatibility

9. Compose Command

Purpose: Build custom images

Usage:

apt-ostree compose [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• tree: Build tree from configuration
• build-image: Build container image
• extensions: Manage extensions

Examples:

# Build tree
apt-ostree compose tree config.yaml

# Build container image
apt-ostree compose build-image --format=docker output.tar

# Manage extensions
apt-ostree compose extensions list

Implementation:

• Parses configuration files
• Builds custom images
• Manages extensions
• Generates container images

10. DB Command

Purpose: Query package database

Usage:

apt-ostree db [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• diff: Show differences between deployments
• list: List packages in deployment
• version: Show package versions

Examples:

# Show differences
apt-ostree db diff deployment1 deployment2

# List packages
apt-ostree db list

# Show versions
apt-ostree db version package-name

Implementation:

• Queries APT package database
• Compares deployments
• Lists package information
• Shows version details

11. Search Command

Purpose: Search for packages

Usage:

apt-ostree search [OPTIONS] QUERY

Options:

• --json: Output in JSON format
• --limit=N: Limit number of results

Examples:

# Search by name
apt-ostree search firefox

# Search by description
apt-ostree search "web browser"

Implementation:

• Uses libapt-pkg for package search
• Searches package metadata
• Returns relevant results
• Supports various search criteria

12. Kargs Command

Purpose: Manage kernel arguments

Usage:

apt-ostree kargs [OPTIONS] [ARGUMENTS]

Options:

• --reboot: Automatically reboot after changes
• --append: Append kernel arguments
• --delete: Delete kernel arguments
• --replace: Replace kernel arguments

Examples:

# Show current kernel arguments
apt-ostree kargs

# Append kernel argument
apt-ostree kargs --append="quiet"

# Delete kernel argument
apt-ostree kargs --delete="quiet"

# Replace kernel arguments
apt-ostree kargs --replace="quiet splash"

Implementation:

• Manages kernel argument state
• Updates boot configuration
• Handles argument modification
• Preserves argument history

13. Initramfs Command

Purpose: Manage initramfs

Usage:

apt-ostree initramfs [SUBCOMMAND] [OPTIONS] [ARGUMENTS]

Subcommands:

• enable: Enable initramfs
• disable: Disable initramfs
• etc: Manage initramfs files

Examples:

# Enable initramfs
apt-ostree initramfs enable

# Disable initramfs
apt-ostree initramfs disable

# Manage files
apt-ostree initramfs etc --track=/etc/fstab

Implementation:

• Manages initramfs state
• Handles initramfs generation
• Tracks initramfs files
• Updates boot configuration

14. Usroverlay Command

Purpose: Create transient overlayfs to /usr

Usage:

apt-ostree usroverlay [OPTIONS] [COMMAND]

Options:

• --init: Initialize overlay
• --cleanup: Clean up overlay

Examples:

# Initialize overlay
apt-ostree usroverlay --init

# Run command in overlay
apt-ostree usroverlay --init -- apt install package

# Clean up overlay
apt-ostree usroverlay --cleanup

Implementation:

• Creates overlayfs mount
• Manages overlay state
• Handles command execution
• Cleans up overlay

15. Apply-Live Command

Purpose: Apply changes to running system

Usage:

apt-ostree apply-live [OPTIONS]

Options:

• --reload: Reload configuration
• --replace: Replace running system

Examples:

# Apply live changes
apt-ostree apply-live

# Apply with reload
apt-ostree apply-live --reload

Implementation:

• Applies changes to running system
• Manages live updates
• Handles configuration reload
• Manages system state

16. Cancel Command

Purpose: Cancel pending transaction

Usage:

apt-ostree cancel [OPTIONS]

Options:

• --force: Force cancellation

Examples:

# Cancel transaction
apt-ostree cancel

# Force cancellation
apt-ostree cancel --force

Implementation:

• Cancels pending transactions
• Cleans up transaction state
• Handles force cancellation
• Manages rollback

17. Cleanup Command

Purpose: Clean up old deployments

Usage:

apt-ostree cleanup [OPTIONS]

Options:

• --base: Clean up base images
• --repomd: Clean up repository metadata
• --rollback: Clean up rollback deployments

Examples:

# Clean up old deployments
apt-ostree cleanup

# Clean up base images
apt-ostree cleanup --base

# Clean up rollback deployments
apt-ostree cleanup --rollback

Implementation:

• Identifies old deployments
• Removes unused deployments
• Cleans up base images
• Manages disk space

18. Reload Command

Purpose: Reload configuration

Usage:

apt-ostree reload [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name

Examples:

# Reload configuration
apt-ostree reload

# Reload specific OS
apt-ostree reload --os=debian

Implementation:

• Reloads system configuration
• Updates repository metadata
• Refreshes package information
• Manages configuration state

19. Reset Command

Purpose: Reset system state

Usage:

apt-ostree reset [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name
• --hard: Hard reset (remove all changes)

Examples:

# Reset system
apt-ostree reset

# Hard reset
apt-ostree reset --hard

Implementation:

• Resets system state
• Removes user changes
• Restores base state
• Manages state reset

20. Refresh-MD Command

Purpose: Refresh repository metadata

Usage:

apt-ostree refresh-md [OPTIONS]

Options:

• --os=OSNAME: Specify operating system name

Examples:

# Refresh metadata
apt-ostree refresh-md

# Refresh specific OS
apt-ostree refresh-md --os=debian

Implementation:

• Downloads repository metadata
• Updates package information
• Refreshes repository state
• Manages metadata cache

21. Initramfs-Etc Command

Purpose: Manage initramfs files

Usage:

apt-ostree initramfs-etc [OPTIONS] [ARGUMENTS]

Options:

• --track: Track file in initramfs
• --untrack: Untrack file from initramfs

Examples:

# Track file
apt-ostree initramfs-etc --track=/etc/fstab

# Untrack file
apt-ostree initramfs-etc --untrack=/etc/fstab

Implementation:

• Manages initramfs file tracking
• Handles file inclusion/exclusion
• Updates initramfs configuration
• Manages file state

Command Architecture

Daemon-Based Execution

All commands follow the same daemon-based architecture:

1. CLI Parsing: Parse command-line arguments
2. Daemon Communication: Request operation via D-Bus
3. Fallback Handling: Use direct system calls if daemon fails
4. Progress Reporting: Show operation progress
5. Result Display: Display operation results

Implementation Pattern

// Command execution pattern
pub fn execute_command(args: &[String]) -> Result<(), Error> {
    // 1. Parse arguments
    let parsed_args = parse_arguments(args)?;
    
    // 2. Try daemon communication
    match connect_to_daemon() {
        Ok(connection) => {
            // Use daemon for operation
            execute_via_daemon(connection, parsed_args)?;
        }
        Err(_) => {
            // Fallback to direct calls
            execute_direct_calls(parsed_args)?;
        }
    }
    
    Ok(())
}

Advanced Features

JSON Output

Many commands support JSON output for programmatic use:

# JSON status output
apt-ostree status --json

# JSON search output
apt-ostree search --json firefox

Verbose Output

Enable detailed output for debugging:

# Verbose upgrade
apt-ostree upgrade --verbose

# Verbose install
apt-ostree install --verbose vim

OSTree Environment Detection

apt-ostree automatically detects if it's running in an OSTree environment:

# Automatic detection
apt-ostree status

# Error if not in OSTree environment
Error: apt-ostree requires an OSTree environment to operate.

This system does not appear to be running on an OSTree deployment.

To use apt-ostree:
1. Ensure you are running on an OSTree-based system
2. Verify that /ostree directory exists
3. Verify that /run/ostree-booted file exists
4. Ensure you have a valid booted deployment

Error Handling

Common Error Scenarios

1. Network Errors: Package download failures
2. Dependency Conflicts: Package dependency issues
3. Disk Space: Insufficient storage space
4. Permission Errors: Insufficient privileges
5. OSTree Errors: Filesystem operation failures
6. Non-OSTree Environment: System not running on OSTree

Error Recovery

• Automatic Rollback: Failed operations automatically rollback
• Manual Recovery: Manual recovery procedures available
• Error Reporting: Detailed error messages and guidance
• Logging: Comprehensive logging for debugging

OSTree Environment Errors

When not running in an OSTree environment, apt-ostree provides clear guidance:

Error: apt-ostree requires an OSTree environment to operate.

This system does not appear to be running on an OSTree deployment.

To use apt-ostree:
1. Ensure you are running on an OSTree-based system
2. Verify that /ostree directory exists
3. Verify that /run/ostree-booted file exists
4. Ensure you have a valid booted deployment

Integration with Other Tools

GUI Integration

• GNOME Software: Integration with GNOME Software Center (planned)
• KDE Discover: Integration with KDE Discover (planned)
• Flatpak: Integration with Flatpak applications (planned)

System Integration

• systemd: Integration with systemd services
• D-Bus: D-Bus interface for other applications
• PolicyKit: Authentication and authorization

APT Integration

• libapt-pkg: Direct integration with APT package management
• APT Cache: Integration with APT package cache
• APT Sources: Integration with APT repository sources

Performance Considerations

Optimization Strategies

1. Parallel Downloads: Concurrent package downloads via APT
2. Caching: Package and metadata caching via APT
3. Delta Updates: Incremental update support
4. Compression: Efficient data compression

Resource Usage

• Memory: Efficient memory usage for large operations
• Disk: Optimized disk usage through OSTree deduplication
• Network: Bandwidth optimization for downloads via APT
• CPU: Parallel processing for package operations

Security Features

Package Verification

• GPG Signatures: Package signature verification via APT
• Checksums: Package integrity checks
• Secure Downloads: HTTPS for package downloads

Access Control

• PolicyKit: Privileged operation authentication
• User Permissions: User-specific permissions
• System Policies: System-wide security policies

Bubblewrap Sandboxing

• Script Execution: Package scripts executed in sandboxed environment
• Namespace Isolation: Process, mount, network namespaces
• Security Controls: Privilege restrictions
• Atomic Context: Script execution in atomic context

APT-Specific Features

APT Database Integration

• Package Information: Direct access to APT package database
• Dependency Resolution: Native APT dependency resolution
• Repository Management: Integration with APT repository system
• Package Metadata: Access to APT package metadata

DEB Package Handling

• Package Extraction: Direct DEB package extraction
• Control File Parsing: APT control file parsing
• Script Execution: DEB package script execution
• Metadata Extraction: Package metadata extraction

Multi-Arch Support

• Architecture Detection: Automatic package architecture detection
• Multi-Arch Types: Support for same, foreign, allowed
• Conflict Prevention: Intelligent handling of architecture-specific paths
• Dependency Resolution: Architecture-aware dependency resolution

Future Enhancements

Planned Features

1. Container Integration: Direct container support
2. Cloud Integration: Cloud deployment support
3. Advanced Search: Enhanced search capabilities
4. Performance Monitoring: Built-in performance monitoring

CLI Improvements

1. Interactive Mode: Interactive command mode
2. Command Completion: Enhanced command completion
3. Progress Indicators: Better progress reporting
4. Configuration Management: Enhanced configuration options

APT Enhancements

1. Advanced Dependency Resolution: Enhanced dependency handling
2. Package Conflict Resolution: Improved conflict resolution
3. Repository Management: Enhanced repository management
4. Package Verification: Enhanced package verification