Simple CLI - Particle-OS Development System

Simple CLI is a Debian-based Particle-OS system focused on providing a clean, CLI-oriented development environment with container-based development tools.

Features

• Base System: Debian Trixie with OSTree
• Container Runtime: Podman with full container support
• Development Tools: Both Toolbox and Distrobox for development environments
• Build System: Just-based automation with comprehensive recipes
• Immutable Design: Atomic updates with rollback capability

Development Environments

Simple CLI provides two powerful development environment tools:

1. Toolbox (Official Debian Package)

Toolbox is the official container-based development environment tool, tightly integrated with the system.

Quick Start

# Create a development environment
toolbox create dev

# Enter the development environment
toolbox enter dev

# Install development tools
apt update
apt install gcc make git python3-pip

# Work on projects without affecting the immutable host

Features

• Native Debian integration - Uses Debian Trixie containers
• Host filesystem access - Full access to your home directory
• Package management - Use APT to install any tools
• System integration - Access to host network, USB devices, display

2. Distrobox (Community Alternative)

Distrobox provides additional flexibility and cross-distribution support.

Quick Start

# Create a development environment
distrobox create dev --image debian:trixie

# Enter the development environment
distrobox enter dev

# Install development tools
apt update
apt install build-essential git python3-pip

# Work on projects with full flexibility

Features

• Cross-distribution support - Can use Ubuntu, Fedora, or other images
• Advanced container management - More flexible than Toolbox
• Multiple backends - Supports both Docker and Podman
• Custom configurations - Highly configurable for specific needs

Using Just Commands

Simple CLI includes comprehensive Just-based automation:

# Setup development environment
just setup-dev

# Create development environments
just create-dev-toolbox      # Create Toolbox environment
just create-dev-distrobox    # Create Distrobox environment

# Enter environments
just dev-toolbox             # Enter Toolbox environment
just dev-distrobox           # Enter Distrobox environment

# Test functionality
just test-toolbox            # Test Toolbox
just test-distrobox          # Test Distrobox

# List all environments
just list-envs               # Show all development environments

# Clean up
just cleanup-envs            # Remove all development environments

When to Use Which Tool?

Use Toolbox When:

• Native Debian development - Working with Debian-specific tools
• System integration - Need tight integration with host system
• Official support - Prefer officially supported tools
• Simple workflows - Basic development environment needs

Use Distrobox When:

• Cross-distribution - Need tools from other distributions
• Custom configurations - Require specific container setups
• Advanced workflows - Complex development environment needs
• Flexibility - Want more control over container configuration

Configuration Files

Toolbox Configuration

• /etc/containers/toolbox.conf - Main Toolbox configuration
• /etc/profile.d/toolbox.sh - Shell integration and welcome messages
• /usr/lib/tmpfiles.d/toolbox.conf - Systemd integration

Distrobox Configuration

• /etc/distrobox/docker.ini - Docker backend configuration
• /etc/distrobox/podman.ini - Podman backend configuration

Building and Testing

# Build the container image
just build

# Test the image
just test

# Generate bootable image
just generate-bootable

# Full pipeline
just pipeline

System Requirements

• Container Runtime: Podman or Docker
• Storage: 10GB+ for development environments
• Memory: 4GB+ RAM recommended
• Architecture: x86_64 (amd64)

Troubleshooting

Common Issues

1. Permission Denied: Ensure your user is in the appropriate groups

   sudo usermod -a -G podman $USER
   newgrp podman
   

2. Container Creation Fails: Check container runtime status

   podman system info
   systemctl status podman.socket
   

3. Network Issues: Verify host networking

   ip addr show
   toolbox enter dev -- ip addr show
   

Getting Help

• Toolbox: containertoolbx.org
• Distrobox: github.com/89luca89/distrobox
• Particle-OS: Project documentation and community

Contributing

Simple CLI is part of the Particle-OS project. Contributions are welcome!

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with just test
5. Submit a pull request

License

This project is part of Particle-OS and follows the same licensing terms.