---
description: Create and manage declarative container specification files
argument-hint: <action> [name/file]
---

# Container Specification Management

Create and manage declarative container specifications.

## Actions

- `/spec create <name>` - Create a new spec file interactively
- `/spec show <file>` - Display parsed spec contents
- `/spec validate <file>` - Validate a spec file
- `/spec apply <file>` - Apply spec to create/update container
- `/spec export <container>` - Export container config to spec

---

## Instructions

### For CREATE:

Guide the user through creating a spec file:

1. Ask for basic info: container name, runtime, primary use case
2. Generate appropriate configuration based on use case

**Development environment:**
```yaml
name: <name>
runtime: docker
profiles:
  - base
  - dev-python
volumes:
  - .:/workspace
working_dir: /workspace
network:
  ports:
    - 8000:8000
```

**GPU/ML workload:**
```yaml
name: <name>
runtime: docker
profiles:
  - base
  - dev-python
gpu:
  enabled: true
  vendor: auto
volumes:
  - ./projects:/workspace
```

3. Write spec file and validate: `gaol spec validate <file>`

### For SHOW:
```bash
gaol spec show <file>
```

### For VALIDATE:
```bash
gaol spec validate <file>
```
Report any errors and suggest fixes.

### For APPLY:
```bash
gaol apply <file> --start
```

### For EXPORT:
```bash
gaol export <container> -o <container>.yaml
```

## Spec File Reference

```yaml
name: container-name        # Required
runtime: docker             # docker, nspawn, libvirt, apple
distro: trixie              # or use image: instead

profiles:
  - base
  - dev-python

resources:
  memory: 4G
  cpus: 2

network:
  ports:
    - 8080:80

volumes:
  - /host/path:/container/path

environment:
  KEY: value
  SECRET: "${secret:NAME}"

gpu:
  enabled: false
  vendor: auto
```
