apt-ostree/docs/apt-ostree-daemon-plan/reference/command-reference.md

📚 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:

-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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

 # 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

# 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.

 # 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.

# 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.

# 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.

# 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.

# 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

# General help
apt-ostree --help

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

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

Examples

# 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.