# bootc state - External Commands Reference

## Overview

This document provides a comprehensive reference for all external commands used by `bootc state` operations. These commands are essential for understanding the dependencies and integration points of the bootc state system.

## Core Commands

### bootc

**Purpose**: Main bootc command for state operations
**Usage**: `bootc state <subcommand> [options...]`
**Dependencies**: None (core command)

#### State Subcommands
- `bootc state wipe-ostree` - Remove all OSTree deployments
- `bootc state help` - Show help information

#### Examples
```bash
# Wipe all OSTree deployments
bootc state wipe-ostree

# Show help
bootc state --help
bootc state wipe-ostree --help
```

## OSTree Commands

### ostree

**Purpose**: OSTree repository operations
**Usage**: `ostree <subcommand> [options...]`
**Dependencies**: ostree package

#### Repository Commands
- `ostree admin status` - Show admin status
- `ostree log` - Show commit log
- `ostree show` - Show commit details
- `ostree refs` - List references
- `ostree ls` - List repository contents
- `ostree cat` - Show file contents
- `ostree checkout` - Checkout files
- `ostree admin pin` - Pin deployments
- `ostree admin unpin` - Unpin deployments
- `ostree admin deploy` - Deploy commits
- `ostree admin rollback` - Rollback deployments
- `ostree admin cleanup` - Clean up deployments
- `ostree fsck` - Check repository integrity

#### Examples
```bash
# Show current status
ostree admin status

# List all references
ostree refs

# Show commit details
ostree show <commit-hash>

# List repository contents
ostree ls <commit-hash>

# Show file contents
ostree cat <commit-hash> /path/to/file

# Checkout files
ostree checkout <commit-hash> /path/to/destination

# Deploy commit
ostree admin deploy <commit-hash>

# Rollback deployment
ostree admin rollback

# Clean up deployments
ostree admin cleanup

# Check repository integrity
ostree fsck
```

### ostree-ext

**Purpose**: Extended OSTree operations
**Usage**: `ostree-ext <subcommand> [options...]`
**Dependencies**: ostree-ext package

#### Examples
```bash
# Container operations
ostree-ext container pull quay.io/myorg/image:latest

# Repository operations
ostree-ext repo create /path/to/repo

# Image operations
ostree-ext image build /path/to/image
```

## System Commands

### systemctl

**Purpose**: Systemd service management
**Usage**: `systemctl <subcommand> [options...]`
**Dependencies**: systemd

#### Service Commands
- `systemctl status` - Show service status
- `systemctl start` - Start service
- `systemctl stop` - Stop service
- `systemctl restart` - Restart service
- `systemctl enable` - Enable service
- `systemctl disable` - Disable service
- `systemctl reload` - Reload service
- `systemctl daemon-reload` - Reload systemd configuration

#### Examples
```bash
# Check service status
systemctl status bootc-*

# Start service
systemctl start bootc-*

# Enable service
systemctl enable bootc-*

# Reload systemd configuration
systemctl daemon-reload
```

### journalctl

**Purpose**: Systemd journal viewing
**Usage**: `journalctl [options...]`
**Dependencies**: systemd

#### Examples
```bash
# Show all logs
journalctl

# Show logs for service
journalctl -u bootc-*

# Show recent logs
journalctl -n 100

# Follow logs
journalctl -f

# Show logs since time
journalctl --since "1 hour ago"

# Show logs with priority
journalctl -p err
```

## Filesystem Commands

### mount

**Purpose**: Filesystem mounting
**Usage**: `mount [options...] <device> <directory>`
**Dependencies**: util-linux

#### Examples
```bash
# Mount filesystem
mount /dev/sda1 /mnt

# Unmount filesystem
umount /mnt

# Check mount points
findmnt

# Mount with options
mount -o ro,noexec /dev/sda1 /mnt
```

### umount

**Purpose**: Unmount filesystems
**Usage**: `umount [options...] <directory>`
**Dependencies**: util-linux

#### Examples
```bash
# Unmount filesystem
umount /mnt

# Force unmount
umount -f /mnt

# Lazy unmount
umount -l /mnt
```

### df

**Purpose**: Disk space usage
**Usage**: `df [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show disk usage
df -h

# Show specific filesystem
df -h /var/lib/bootc

# Show inode usage
df -i

# Show all filesystems
df -a
```

### du

**Purpose**: Directory space usage
**Usage**: `du [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show directory usage
du -h /var/lib/bootc

# Show total usage
du -sh /var/lib/bootc

# Show usage by subdirectory
du -h --max-depth=1 /var/lib/bootc

# Show usage of all files
du -ah /var/lib/bootc
```

### lsblk

**Purpose**: List block devices
**Usage**: `lsblk [options...]`
**Dependencies**: util-linux

#### Examples
```bash
# List block devices
lsblk

# Show device tree
lsblk -f

# Show device sizes
lsblk -b

# Show device types
lsblk -d
```

## Process Commands

### ps

**Purpose**: Process status
**Usage**: `ps [options...]`
**Dependencies**: procps

#### Examples
```bash
# Show all processes
ps aux

# Show process tree
ps -ef

# Show specific process
ps -p 1234

# Show processes by user
ps -u username
```

### kill

**Purpose**: Send signals to processes
**Usage**: `kill [options...] <pid>`
**Dependencies**: util-linux

#### Examples
```bash
# Kill process
kill 1234

# Force kill process
kill -9 1234

# Send signal
kill -TERM 1234

# Kill by name
pkill process_name
```

### pkill

**Purpose**: Kill processes by name
**Usage**: `pkill [options...] <pattern>`
**Dependencies**: procps

#### Examples
```bash
# Kill by name
pkill process_name

# Force kill by name
pkill -9 process_name

# Kill by pattern
pkill -f "pattern"
```

## File Commands

### ls

**Purpose**: List directory contents
**Usage**: `ls [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# List files
ls

# List with details
ls -l

# List all files
ls -a

# List with human readable sizes
ls -lh

# List with recursive
ls -R

# List with sort by time
ls -lt
```

### find

**Purpose**: Find files
**Usage**: `find [path...] [expression]`
**Dependencies**: findutils

#### Examples
```bash
# Find files by name
find /path -name "*.txt"

# Find files by type
find /path -type f

# Find files by size
find /path -size +100M

# Find files by modification time
find /path -mtime -7

# Find files by permissions
find /path -perm 644
```

### stat

**Purpose**: File status
**Usage**: `stat [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show file status
stat file.txt

# Show in custom format
stat -c "%n %s %Y" file.txt

# Show filesystem status
stat -f /path

# Show with format
stat --format="%n: %s bytes" file.txt
```

## Archive Commands

### tar

**Purpose**: Archive operations
**Usage**: `tar [options...] <archive> [file...]`
**Dependencies**: tar

#### Examples
```bash
# Create archive
tar -cf archive.tar file1 file2

# Extract archive
tar -xf archive.tar

# List archive contents
tar -tf archive.tar

# Create compressed archive
tar -czf archive.tar.gz file1 file2

# Extract compressed archive
tar -xzf archive.tar.gz
```

### gzip

**Purpose**: Compression
**Usage**: `gzip [options...] [file...]`
**Dependencies**: gzip

#### Examples
```bash
# Compress file
gzip file.txt

# Decompress file
gzip -d file.txt.gz

# Compress with custom level
gzip -9 file.txt

# Keep original file
gzip -k file.txt
```

## System Information Commands

### uname

**Purpose**: System information
**Usage**: `uname [options...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show system name
uname

# Show all information
uname -a

# Show kernel name
uname -s

# Show kernel version
uname -r

# Show machine type
uname -m
```

### hostname

**Purpose**: Hostname operations
**Usage**: `hostname [options...]`
**Dependencies**: hostname

#### Examples
```bash
# Show hostname
hostname

# Show FQDN
hostname -f

# Show short hostname
hostname -s

# Show domain name
hostname -d
```

### lscpu

**Purpose**: CPU information
**Usage**: `lscpu [options...]`
**Dependencies**: util-linux

#### Examples
```bash
# Show CPU information
lscpu

# Show in JSON format
lscpu -J

# Show in extended format
lscpu -e

# Show in parseable format
lscpu -p
```

### free

**Purpose**: Memory information
**Usage**: `free [options...]`
**Dependencies**: procps

#### Examples
```bash
# Show memory usage
free

# Show in human readable format
free -h

# Show in bytes
free -b

# Show with total
free -t

# Show with wide format
free -w
```

## Network Commands

### curl

**Purpose**: HTTP client for registry operations
**Usage**: `curl [options...] <url>`
**Dependencies**: curl

#### Examples
```bash
# Download file
curl -O https://example.com/file.tar

# Get HTTP headers
curl -I https://example.com

# POST data
curl -X POST -d "data" https://example.com

# With authentication
curl -u username:password https://example.com

# With custom headers
curl -H "Authorization: Bearer token" https://example.com
```

### wget

**Purpose**: HTTP client for downloading files
**Usage**: `wget [options...] <url>`
**Dependencies**: wget

#### Examples
```bash
# Download file
wget https://example.com/file.tar

# Download with progress
wget --progress=bar https://example.com/file.tar

# Download recursively
wget -r https://example.com/

# Download with authentication
wget --user=username --password=password https://example.com
```

## Container Commands

### podman

**Purpose**: Container runtime
**Usage**: `podman <subcommand> [options...]`
**Dependencies**: podman

#### Examples
```bash
# List containers
podman ps

# List images
podman images

# Pull image
podman pull quay.io/myorg/image:latest

# Run container
podman run -it image:latest

# Build image
podman build -t myimage:latest .

# Inspect image
podman inspect image:latest
```

### docker

**Purpose**: Alternative container runtime
**Usage**: `docker <subcommand> [options...]`
**Dependencies**: docker

#### Examples
```bash
# List containers
docker ps

# List images
docker images

# Pull image
docker pull quay.io/myorg/image:latest

# Run container
docker run -it image:latest

# Build image
docker build -t myimage:latest .
```

## Development Commands

### make

**Purpose**: Build automation
**Usage**: `make [target...]`
**Dependencies**: make

#### Examples
```bash
# Build project
make

# Clean build
make clean

# Install
make install

# Run tests
make test

# Update generated files
make update-generated
```

### cargo

**Purpose**: Rust package manager
**Usage**: `cargo <subcommand> [options...]`
**Dependencies**: rust

#### Examples
```bash
# Build project
cargo build

# Run project
cargo run

# Run tests
cargo test

# Check code
cargo check

# Update dependencies
cargo update
```

### git

**Purpose**: Version control
**Usage**: `git <subcommand> [options...]`
**Dependencies**: git

#### Examples
```bash
# Clone repository
git clone https://github.com/containers/bootc.git

# Check status
git status

# Add files
git add .

# Commit changes
git commit -m "message"

# Push changes
git push
```

## Monitoring Commands

### top

**Purpose**: Process monitoring
**Usage**: `top [options...]`
**Dependencies**: procps

#### Examples
```bash
# Show processes
top

# Show specific user
top -u username

# Show specific process
top -p 1234

# Show with custom delay
top -d 5

# Show with custom sort
top -o %CPU
```

### htop

**Purpose**: Interactive process monitoring
**Usage**: `htop [options...]`
**Dependencies**: htop

#### Examples
```bash
# Show processes
htop

# Show specific user
htop -u username

# Show specific process
htop -p 1234

# Show with custom delay
htop -d 5
```

### iotop

**Purpose**: I/O monitoring
**Usage**: `iotop [options...]`
**Dependencies**: iotop

#### Examples
```bash
# Show I/O usage
iotop

# Show only processes doing I/O
iotop -o

# Show with custom delay
iotop -d 5

# Show with custom refresh
iotop -n 10
```

## Security Commands

### openssl

**Purpose**: SSL/TLS operations
**Usage**: `openssl <command> [options...]`
**Dependencies**: openssl

#### Examples
```bash
# Generate private key
openssl genrsa -out key.pem 2048

# Generate certificate
openssl req -new -x509 -key key.pem -out cert.pem

# Verify certificate
openssl verify cert.pem

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Generate hash
openssl dgst -sha256 file.txt
```

### gpg

**Purpose**: GPG operations
**Usage**: `gpg [options...]`
**Dependencies**: gnupg

#### Examples
```bash
# Generate key pair
gpg --gen-key

# List keys
gpg --list-keys

# Sign file
gpg --sign file.txt

# Verify signature
gpg --verify file.txt.asc

# Encrypt file
gpg --encrypt file.txt
```

## Bootloader Commands

### grub-mkconfig

**Purpose**: Generate GRUB configuration
**Usage**: `grub-mkconfig [options...]`
**Dependencies**: grub2

#### Examples
```bash
# Generate GRUB config
grub-mkconfig -o /boot/grub/grub.cfg

# Generate with specific output
grub-mkconfig -o /boot/grub2/grub.cfg

# Generate with verbose output
grub-mkconfig -v -o /boot/grub/grub.cfg
```

### grub-install

**Purpose**: Install GRUB bootloader
**Usage**: `grub-install [options...] <device>`
**Dependencies**: grub2

#### Examples
```bash
# Install GRUB
grub-install /dev/sda

# Install with specific directory
grub-install --boot-directory=/boot /dev/sda

# Install with verbose output
grub-install -v /dev/sda
```

### efibootmgr

**Purpose**: EFI boot manager
**Usage**: `efibootmgr [options...]`
**Dependencies**: efibootmgr

#### Examples
```bash
# List boot entries
efibootmgr

# Create boot entry
efibootmgr -c -d /dev/sda -p 1 -L "Bootc" -l /EFI/bootc/grubx64.efi

# Delete boot entry
efibootmgr -b 0000 -B

# Set boot order
efibootmgr -o 0000,0001,0002
```

## Recovery Commands

### chroot

**Purpose**: Change root directory
**Usage**: `chroot [options...] <directory> <command>`
**Dependencies**: coreutils

#### Examples
```bash
# Change root
chroot /mnt /bin/bash

# Change root with specific command
chroot /mnt /bin/ls

# Change root with environment
chroot /mnt env -i /bin/bash
```

### mount

**Purpose**: Mount filesystems for recovery
**Usage**: `mount [options...] <device> <directory>`
**Dependencies**: util-linux

#### Examples
```bash
# Mount root filesystem
mount /dev/sda1 /mnt

# Mount boot filesystem
mount /dev/sda2 /mnt/boot

# Mount with specific options
mount -o ro /dev/sda1 /mnt
```

### umount

**Purpose**: Unmount filesystems after recovery
**Usage**: `umount [options...] <directory>`
**Dependencies**: util-linux

#### Examples
```bash
# Unmount filesystem
umount /mnt

# Unmount all filesystems
umount -a

# Force unmount
umount -f /mnt
```

This comprehensive reference covers all external commands used by the bootc state system, providing examples and usage patterns for each command.