robojerk
306a68b89a
- Fix parallel execution logic to properly handle JoinHandle<Result<R, E>> types - Use join_all instead of try_join_all for proper Result handling - Fix double question mark (??) issue in parallel execution methods - Clean up unused imports in parallel and cache modules - Ensure all performance optimization modules compile successfully - Fix CI build failures caused by compilation errors
565 lines
13 KiB
Markdown
565 lines
13 KiB
Markdown
# 📚 **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.*
|