# 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
```bash
# 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
```bash
# 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:

```bash
# 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

```bash
# 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
   ```bash
   sudo usermod -a -G podman $USER
   newgrp podman
   ```

2. **Container Creation Fails**: Check container runtime status
   ```bash
   podman system info
   systemctl status podman.socket
   ```

3. **Network Issues**: Verify host networking
   ```bash
   ip addr show
   toolbox enter dev -- ip addr show
   ```

### Getting Help

- **Toolbox**: [containertoolbx.org](https://containertoolbox.org/)
- **Distrobox**: [github.com/89luca89/distrobox](https://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.