# 📚 **apt-ostree Command Reference**

## 🎯 **Overview**

This document provides a complete reference for all apt-ostree CLI commands, organized by functionality and including examples, flags, and usage patterns. All commands maintain 100% compatibility with rpm-ostree.

## 🔧 **Global Options**

All commands support these global options:

```bash
-h, --help          Show help message
-V, --version       Show version information
-q, --quiet         Suppress output
-v, --verbose       Verbose output
--debug             Enable debug output
```

## 📊 **System Status Commands**

### **`status`** - Show System Status
Display current system status including OSTree deployments and package information.

```bash
# Basic status
apt-ostree status

# Status for specific OS
apt-ostree status --os debian

# JSON output
apt-ostree status --json

# Verbose output
apt-ostree status --verbose
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-j, --json` - Output in JSON format
- `-v, --verbose` - Verbose output

### **`db`** - Database Operations
Query and manage the package database.

```bash
# List packages
apt-ostree db list

# Show package differences
apt-ostree db diff

# Show database version
apt-ostree db version
```

**Subcommands:**
- `list` - List packages in database
- `diff` - Show differences between deployments
- `version` - Show database version information

## 🚀 **System Management Commands**

### **`upgrade`** - Upgrade System
Perform a system upgrade to the latest available version.

```bash
# Basic upgrade
apt-ostree upgrade

# Upgrade with reboot
apt-ostree upgrade --reboot

# Upgrade specific OS
apt-ostree upgrade --os debian

# Preview upgrade
apt-ostree upgrade --preview
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after upgrade
- `--preview` - Preview changes without applying
- `-y, --yes` - Answer yes to prompts

### **`deploy`** - Deploy Specific Commit
Deploy a specific OSTree commit.

```bash
# Deploy specific commit
apt-ostree deploy <COMMIT>

# Deploy with reboot
apt-ostree deploy <COMMIT> --reboot

# Deploy with options
apt-ostree deploy <COMMIT> --os debian --reboot
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after deployment
- `--preview` - Preview deployment without applying

### **`rollback`** - Rollback to Previous Deployment
Revert to the previously booted deployment.

```bash
# Basic rollback
apt-ostree rollback

# Rollback with reboot
apt-ostree rollback --reboot

# Rollback specific OS
apt-ostree rollback --os debian
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after rollback

## 📦 **Package Management Commands**

### **`install`** - Install Packages
Install additional packages into the current deployment.

```bash
# Install single package
apt-ostree install vim

# Install multiple packages
apt-ostree install vim emacs nano

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

# Install specific version
apt-ostree install vim=2:9.0.1378-1
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after installation
- `-y, --yes` - Answer yes to prompts

### **`uninstall`** - Remove Packages
Remove previously installed packages.

```bash
# Remove single package
apt-ostree uninstall vim

# Remove multiple packages
apt-ostree uninstall vim emacs

# Remove with reboot
apt-ostree uninstall vim --reboot
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after removal
- `-y, --yes` - Answer yes to prompts

### **`override`** - Package Overrides
Manage base package overrides.

```bash
# Replace package
apt-ostree override replace vim 2:9.0.1378-1

# Reset package override
apt-ostree override reset vim

# List overrides
apt-ostree override list
```

**Subcommands:**
- `replace <PACKAGE> <VERSION>` - Replace base package with different version
- `reset <PACKAGE>` - Reset package to base version
- `list` - List current package overrides

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after override
- `--lock-finalization` - Lock finalization

## 🔄 **Advanced System Commands**

### **`usroverlay`** - User Overlays
Apply transient overlayfs modifications to /usr.

```bash
# Apply overlay
apt-ostree usroverlay apply my-overlay /path/to/source /usr/local/custom

# List overlays
apt-ostree usroverlay list

# Reset overlay
apt-ostree usroverlay reset my-overlay

# Remove overlay
apt-ostree usroverlay remove my-overlay
```

**Subcommands:**
- `apply <NAME> <SOURCE> <TARGET>` - Apply user overlay
- `list` - List current user overlays
- `reset <NAME>` - Reset overlay to base state
- `remove <NAME>` - Remove user overlay

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `--read-only` - Make overlay read-only
- `--allow-other` - Allow other users to access
- `--default-permissions` - Use default permissions

### **`apply-live`** - Live Updates
Apply changes to the running system without rebooting.

```bash
 # Apply live update
apt-ostree apply-live apply <DEPLOYMENT>

# Show live update status
apt-ostree apply-live status

# Rollback live update
apt-ostree apply-live rollback <UPDATE_ID>
```

**Subcommands:**
- `apply <DEPLOYMENT>` - Apply live update to deployment
- `status` - Show live update status
- `rollback <UPDATE_ID>` - Rollback live update

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after live update
- `--lock-finalization` - Lock finalization

### **`compose`** - Tree Composition
Compose and manage OSTree trees.

```bash
# Compose tree
apt-ostree compose tree treefile.yml

# Install packages in tree
apt-ostree compose install treefile.yml vim emacs

# Post-process tree
apt-ostree compose postprocess treefile.yml

# Commit tree
apt-ostree compose commit treefile.yml
```

**Subcommands:**
- `tree <TREEFILE>` - Compose tree from treefile
- `install <TREEFILE> <PACKAGES...>` - Install packages in tree
- `postprocess <TREEFILE>` - Post-process composed tree
- `commit <TREEFILE>` - Commit composed tree

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `--output-dir <DIR>` - Output directory for artifacts

## 🔧 **System Configuration Commands**

### **`initramfs`** - Initramfs Management
Manage initramfs generation and configuration.

```bash
# Regenerate initramfs
apt-ostree initramfs regenerate

# Enable initramfs
apt-ostree initramfs enable

# Disable initramfs
apt-ostree initramfs disable
```

**Subcommands:**
- `regenerate` - Regenerate initramfs
- `enable` - Enable initramfs generation
- `disable` - Disable initramfs generation

**Options:**
- `-o, --os <OSNAME>` - Operating system name

### **`kargs`** - Kernel Arguments
Query and modify kernel command-line arguments.

```bash
# Get kernel arguments
apt-ostree kargs get

# Set kernel arguments
apt-ostree kargs set console=ttyS0

# Delete kernel arguments
apt-ostree kargs delete console

# Reset kernel arguments
apt-ostree kargs reset
```

**Subcommands:**
- `get` - Get current kernel arguments
- `set <ARGS...>` - Set kernel arguments
- `delete <ARGS...>` - Delete kernel arguments
- `reset` - Reset to default kernel arguments

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after changes

### **`rebase`** - Rebase to Different Base
Switch to a different base tree.

```bash
# Rebase to different base
apt-ostree rebase <NEW_BASE>

# Rebase with reboot
apt-ostree rebase <NEW_BASE> --reboot

# Preview rebase
apt-ostree rebase <NEW_BASE> --preview
```

**Options:**
- `-o, --os <OSNAME>` - Operating system name
- `-r, --reboot` - Reboot after rebase
- `--preview` - Preview changes without applying

## 🧹 **System Maintenance Commands**

### **`cleanup`** - Clean Up System
Clear cached and pending data.

```bash
# Basic cleanup
apt-ostree cleanup

# Clean specific items
apt-ostree cleanup --pending --cache

# Force cleanup
apt-ostree cleanup --force
```

**Options:**
- `--pending` - Clean pending deployments
- `--cache` - Clean package cache
- `--force` - Force cleanup operations

### **`refresh-md`** - Refresh Metadata
Refresh package repository metadata.

```bash
# Refresh metadata
apt-ostree refresh-md

# Refresh specific repository
apt-ostree refresh-md --repo <REPO>
```

**Options:**
- `--repo <REPO>` - Specific repository to refresh

### **`reload`** - Reload Configuration
Reload system configuration.

```bash
# Reload configuration
apt-ostree reload

# Reload specific components
apt-ostree reload --daemon --config
```

**Options:**
- `--daemon` - Reload daemon configuration
- `--config` - Reload system configuration

### **`reset`** - Reset System State
Reset system to clean state.

```bash
# Reset system
apt-ostree reset

# Reset with reboot
apt-ostree reset --reboot

# Reset specific components
apt-ostree reset --packages --overrides
```

**Options:**
- `-r, --reboot` - Reboot after reset
- `--packages` - Reset package installations
- `--overrides` - Reset package overrides

## 🐳 **Container and Image Commands**

### **`container`** - Container Operations
Manage container images and operations.

```bash
 # List containers
apt-ostree container list

# Pull container
apt-ostree container pull <IMAGE>

# Push container
apt-ostree container push <IMAGE>
```

**Subcommands:**
- `list` - List available containers
- `pull <IMAGE>` - Pull container image
- `push <IMAGE>` - Push container image

### **`image`** - Image Operations
Manage system images.

```bash
# Build image
apt-ostree image build <CONFIG>

# Export image
apt-ostree image export <IMAGE> <FORMAT>

# Import image
apt-ostree image import <FILE>
```

**Subcommands:**
- `build <CONFIG>` - Build system image
- `export <IMAGE> <FORMAT>` - Export image in format
- `import <FILE>` - Import image from file

## 🔌 **Remote Management Commands**

### **`remote`** - Remote Management
Manage remote repositories and sources.

```bash
# List remotes
apt-ostree remote list

# Add remote
apt-ostree remote add <NAME> <URL>

# Remove remote
apt-ostree remote remove <NAME>

# Show remote info
apt-ostree remote show <NAME>
```

**Subcommands:**
- `list` - List configured remotes
- `add <NAME> <URL>` - Add new remote
- `remove <NAME>` - Remove remote
- `show <NAME>` - Show remote information

## 🎮 **Daemon Control Commands**

### **`start-daemon`** - Start Daemon
Start the apt-ostree daemon.

```bash
# Start daemon
apt-ostree start-daemon

# Start with options
apt-ostree start-daemon --foreground --debug
```

**Options:**
- `--foreground` - Run in foreground
- `--debug` - Enable debug mode

### **`stop-daemon`** - Stop Daemon
Stop the apt-ostree daemon.

```bash
# Stop daemon
apt-ostree stop-daemon

# Force stop
apt-ostree stop-daemon --force
```

**Options:**
- `--force` - Force stop daemon

## 📋 **Command Categories Summary**

| Category | Commands | Description |
|----------|----------|-------------|
| **Status** | `status`, `db` | System information and database queries |
| **Management** | `upgrade`, `deploy`, `rollback` | System deployment and updates |
| **Packages** | `install`, `uninstall`, `override` | Package management and overrides |
| **Advanced** | `usroverlay`, `apply-live`, `compose` | Advanced system features |
| **Configuration** | `initramfs`, `kargs`, `rebase` | System configuration |
| **Maintenance** | `cleanup`, `refresh-md`, `reload`, `reset` | System maintenance |
| **Containers** | `container`, `image` | Container and image management |
| **Remotes** | `remote` | Remote repository management |
| **Daemon** | `start-daemon`, `stop-daemon` | Daemon control |

## 🔍 **Finding Commands**

### **By Functionality**
- **Package Management**: `install`, `uninstall`, `override`
- **System Updates**: `upgrade`, `deploy`, `rollback`
- **Configuration**: `initramfs`, `kargs`, `rebase`
- **Advanced Features**: `usroverlay`, `apply-live`, `compose`

### **By Privilege Level**
- **Local Commands**: `status`, `db`, `pkg` (no root required)
- **Root Commands**: Most commands require root privileges
- **Daemon Commands**: `start-daemon`, `stop-daemon`

### **By System Impact**
- **Read-Only**: `status`, `db`, `list` commands
- **System Changes**: `install`, `upgrade`, `deploy`
- **Configuration**: `kargs`, `initramfs`, `rebase`

## 📖 **Getting Help**

### **Command Help**
```bash
# General help
apt-ostree --help

# Command help
apt-ostree <COMMAND> --help

# Subcommand help
apt-ostree <COMMAND> <SUBCOMMAND> --help
```

### **Examples**
```bash
# Show examples for command
apt-ostree <COMMAND> --help | grep -A 10 "EXAMPLES"

# Run with verbose output
apt-ostree <COMMAND> --verbose
```

---

*This command reference provides comprehensive coverage of all apt-ostree CLI commands. For detailed implementation information, refer to the architecture documents in the `docs/apt-ostree-daemon-plan/architecture/` directory.*