breadcrumb-the-shire/docs/reference-cli-commands.md

# CLI-Kommandoreferenz

Letzte Aktualisierung: 2026-04-01

## Einstiegspunkt

Alle CLI-Kommandos laufen über einen einzigen Einstiegspunkt:

```bash
php bin/console <command> [argumente] [optionen]
```

Übersicht aller verfügbaren Kommandos:

```bash
php bin/console list
```

Hilfe zu einem einzelnen Kommando:

```bash
php bin/console <command> --help
```

## Kommandos

### module:sync

Fuehrt den vollstaendigen Runtime-Sync aus: `db-migrate` → `migrate` → `permissions-sync` → `build` → `assets-sync`.

```bash
docker compose exec php php bin/console module:sync
```

Nötig nach jeder Änderung an Modulen, Manifesten, Routen oder `APP_ENABLED_MODULES` — und nach jedem `git pull`, der Schema-Updates unter `db/updates/*.sql` mitbringt.

Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist dieser Befehl die Lösung.

Maschinenlesbar:

```bash
docker compose exec php php bin/console module:sync --format=json
```

### db:migrate

Wendet idempotente Core-Schema-Updates aus `db/updates/*.sql` an. Angewendete Files werden in der Tabelle `core_migrations` getrackt; jeder Lauf wendet nur neu hinzugekommene Files an.

Jede `db/updates/*.sql` MUSS idempotent sein (`CREATE TABLE IF NOT EXISTS`, `INSERT … ON DUPLICATE KEY UPDATE`, etc.) — Erstlauf gegen ein bereits bestehendes Schema ist damit ein No-op.

```bash
docker compose exec php php bin/console db:migrate
```

`module:sync` ruft den Befehl als ersten Schritt automatisch auf. Direktaufruf nützlich, wenn nur DB-Updates gewuenscht sind ohne Module-Build.

Status-Anzeige (kein Schreibzugriff):

```bash
docker compose exec php php bin/console db:migrate --status
```

Listet `applied:` und `pending:` separat — nützlich beim Debugging veralteter Schemata.

### module:migrate

Wendet ausstehende SQL-Migrationen aus aktiven Modulen an.

```bash
docker compose exec php php bin/console module:migrate
```

### module:permissions-sync

Synchronisiert Modul-Permissions in die DB. Deaktiviert verwaiste System-Permissions (`is_system=1`), die kein aktives Modul mehr beansprucht.

```bash
docker compose exec php php bin/console module:permissions-sync
```

### module:build

Baut die Runtime-Seitenstruktur (`storage/runtime/pages/`) mit Symlinks zu Modul-Pages.

```bash
docker compose exec php php bin/console module:build
```

### module:assets-sync

Publiziert Modul-Assets nach `web/modules/<id>/`.

```bash
docker compose exec php php bin/console module:assets-sync
```

### module:deactivate

Fuehrt den optionalen Deactivation-Handler eines Moduls aus.

```bash
docker compose exec php php bin/console module:deactivate <module-id> --confirm
docker compose exec php php bin/console module:deactivate <module-id> --dry-run
```

Das Modul muss nicht in der Aktivliste stehen. `--dry-run` validiert den Handler ohne Ausführung.

### scheduler:run

Fuehrt faellige Scheduler-Jobs aus.

```bash
docker compose exec php php bin/console scheduler:run
```

Der Docker-Scheduler-Service ruft dieses Kommando automatisch alle 60 Sekunden auf.

### module:validate

Validiert Manifest, Klassen und Struktur eines Moduls. Prüft JSON-Schema-Compliance des `module.php`, Namespace-Konventionen, Interface-Implementierungen, Permission-Key-Formate und Verzeichnisstruktur.

```bash
docker compose exec php php bin/console module:validate <module-id>
docker compose exec php php bin/console module:validate --all
```

`--all` validiert alle Module auf Disk (`modules/*/module.php`) auf einmal.

### make:module

Erzeugt die vollstaendige Verzeichnisstruktur für ein neues Modul inkl. Manifest, ContainerRegistrar-Stub, AuthorizationPolicy-Stub und leeren Verzeichnissen.

```bash
docker compose exec php php bin/console make:module <module-id>
```

Argument `module-id` muss dem Pattern `[a-z][a-z0-9-]*` entsprechen.

### doctor

Fuehrt System-Gesundheitschecks aus (ENV, DB, RBAC, Scheduler-Heartbeat).

```bash
docker compose exec php php bin/console doctor
```

Siehe `/docs/howto-betriebscheck-doctor.md` für Details.

Maschinenlesbar:

```bash
docker compose exec php php bin/console doctor --format=json
```

## Developer-Orchestrator (`bin/dev`)

Fuer lokalen Workflow gibt es zusaetzlich den Dev-Orchestrator:

```bash
bin/dev init
bin/dev up
bin/dev down
bin/dev logs [service]
bin/dev console module:sync
bin/dev qa
bin/dev qa-required
bin/dev qa-extended
```

`bin/dev console ...` delegiert intern auf `docker compose exec -T php php bin/console ...`.
`bin/dev qa` ist ein Alias für `bin/dev qa-required`.

## Neue Kommandos anlegen

1. Klasse in `core/Console/Commands/` erstellen, die `MintyPHP\Console\Command` erweitert.
2. `name()`, `description()` und `execute()` implementieren.
3. Optional: `usage()` für `--help`-Ausgabe überschreiben.

Das Kommando wird automatisch erkannt — kein manuelles Registrieren nötig.

Beispiel:

```php
namespace MintyPHP\Console\Commands\Make;

use MintyPHP\Console\Command;

final class ModuleCommand extends Command
{
    public function name(): string { return 'make:module'; }
    public function description(): string { return 'Scaffold a new module'; }

    public function execute(array $args, array $options): int
    {
        // ...
        return 0;
    }
}
```

## Bootstrap-Helfer

Die `Command`-Basisklasse stellt Helfer bereit:

| Methode | Zweck |
|---|---|
| `$this->bootstrapApp($channel)` | App-Bootstrap für Nicht-Modul-Kommandos |
| `$this->projectRoot()` | Gibt den absoluten Projekt-Root-Pfad zurueck |