# Particle-OS Simple-CLI

## Overview

Particle-OS Simple-CLI is a development and testing environment that demonstrates the core Particle-OS concepts working together. It inherits directly from the Debian Atomic foundation and integrates all three core Particle-OS tools:

- **apt-ostree**: Atomic package management
- **bootupd**: Bootloader update management  
- **bootc**: Container deployment and management

## Architecture

```
Debian Atomic (proven foundation)
    ↓
Particle-OS Simple-CLI
    ↓
Integrated tools: apt-ostree + bootupd + bootc
```

## Features

- ✅ **Clean Architecture**: Direct inheritance from Debian Atomic
- ✅ **Tool Integration**: All three Particle-OS tools working together
- ✅ **Concept Proofing**: Atomic update workflow demonstrated
- ✅ **SSH Access**: Remote access configured and ready
- ✅ **OSTree Foundation**: Full OSTree system with all features

## Quick Start

### Build the Container

```bash
just build-with-tools-ssh
```

### Test the Integration

```bash
just test
```

### Run the Demo

```bash
./demo-concepts.sh
```

## Available Commands

- `verify-tools` - Verify all Particle-OS tools are available
- `simple-cli-welcome` - Show welcome message and available commands
- `demo-concepts.sh` - Demonstrate all tools working together

## Tool Status

| Tool | Status | Version | Notes |
|------|--------|---------|-------|
| apt-ostree | ✅ Working | 0.1.0 | 1,470 packages available |
| bootupd | ✅ Working | 0.2.28 | EFI components detected |
| bootc | ✅ Working | 1.6.0 | Container deployment ready |
| OSTree | ✅ Working | 2025.2 | Full feature set |

## Testing

### Basic Functionality Test

```bash
podman run --rm simple-cli:latest /usr/local/bin/verify-tools
```

### Concept Demonstration

```bash
podman run --rm simple-cli:latest bash -c "apt-ostree list | head -5"
podman run --rm simple-cli:latest bash -c "bootupctl status"
podman run --rm simple-clI:latest bash -c "bootc --help"
```

## Development

### Project Structure

```
simple-cli/
├── Containerfile          # Container definition
├── justfile              # Build automation
├── tools/                # Integrated .deb packages
├── demo-concepts.sh      # Concept demonstration
├── README.md             # This file
└── output/               # Generated outputs
```

### Build Recipes

- `just build-with-tools-ssh` - Build with SSH and tools
- `just test` - Test the built container
- `just clean` - Clean build artifacts

## Integration Status

### What's Working

- ✅ All three Particle-OS tools integrated
- ✅ Tools can communicate and work together
- ✅ OSTree foundation fully functional
- ✅ SSH server configured and ready
- ✅ Clean architecture proven

### What's Next

- 🚧 Bootable image creation (technical challenges)
- 🚧 QEMU testing and validation
- 🚧 End-to-end atomic update workflow
- 🚧 Production deployment

## Troubleshooting

### Common Issues

1. **Container registry issues**: Use full image IDs instead of short names
2. **Permission issues**: Run with `--privileged` flag when needed
3. **Storage access**: Mount volumes explicitly for file access

### Debug Commands

```bash
# Check tool availability
podman run --rm simple-cli:latest which bootc

# Verify OSTree status
podman run --rm simple-cli:latest ostree --version

# Test package management
podman run --rm simple-cli:latest apt-ostree list | head -10
```

## Contributing

This project demonstrates the core Particle-OS concepts. To contribute:

1. Test the integration with different tool combinations
2. Improve the demonstration scripts
3. Add new testing scenarios
4. Document any discovered issues or solutions

## License

Part of the Particle-OS project - Debian-based immutable operating system.
