Admidio-Kommandozeilenschnittstelle [Admidio-Wiki]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Admidio-Kommandozeilenschnittstelle ======

Die Admidio-Kommandozeilenschnittstelle (CLI) stellt eine skriptfähige Administrationsschnittstelle bereit, über die Admidio direkt aus einer Shell verwaltet werden kann.

Die ausführbare Datei liegt im obersten Admidio-Verzeichnis und heißt ''admidio''. Sie wird direkt in einer Shell im Admidio-Verzeichnis ausgeführt:
<code bash>
www-data@server.example.com:~/html$ ./admidio status
Organization: TEST
Filesystem:   5.1.0 Beta 1
Database:     5.1.0-Beta.1
Update step:  620
Status:       OK
</code>


Die CLI verwendet dieselben Admidio-Entities, Services, Berechtigungen, Organisationskontexte und dieselbe Datenbank wie die Webanwendung. Sie eignet sich deshalb sowohl für die interaktive Administration als auch für Automatisierungen, ohne dass Admidio-Geschäftslogik in externen Skripten nachgebaut werden muss.

Typische Anwendungsfälle sind:

  * Admidio-Version, Installationsstatus und verfügbare Updates prüfen;
  * Admidio ohne browserbasierten Installer installieren;
  * Organisationseinstellungen lesen und ändern;
  * Benutzer, Gruppen, Mitgliedschaften, Listen und Berechtigungen anlegen, anzeigen und pflegen;
  * Registrierungen, Benutzerbeziehungen und Profilfelder pflegen;
  * Kategorien, Menüeinträge, Ankündigungen, Foren, Links und Nachrichten pflegen;
  * Inventardaten importieren, exportieren und pflegen;
  * Veranstaltungen und Räume pflegen;
  * mit Dokumenten, Dateien und Fotoalben arbeiten;
  * Changelog- und Kategorieauswertungsdaten anzeigen;
  * Plugins, SSO-Clients und SSO-Schlüssel administrieren;
  * Sessions und Auto-Login-Daten ungültig machen bzw. bereinigen;
  * Datenbanksicherungen erstellen und Wartungsoperationen ausführen;
  * Admidio aus Wartungsskripten, Cronjobs und Deployment-Systemen verwenden;
  * andere Anwendungen über eine skriptfähige Administrationsschnittstelle an Admidio anbinden.

Die genaue Liste der Befehle, Argumente und befehlsspezifischen Optionen steht in der [[en:2.0:cli:commands|CLI-Befehlsreferenz (Englisch)]].

Entwickler, die einem Admidio-Modul zusätzliche CLI-Befehle hinzufügen möchten, finden weitere Informationen unter [[de:entwickler:cli|CLI-Befehle zu Admidio-Modulen hinzufügen]].

===== Voraussetzungen und Bootstrap =====

Die meisten Befehle arbeiten mit einer vorhandenen Admidio-Installation. Dafür werden benötigt:

  * eine installierte Admidio-Instanz;
  * PHP CLI;
  * die PHP-Erweiterungen, die auch die entsprechende Admidio-Installation benötigt;
  * Dateisystemzugriff auf das Admidio-Verzeichnis und ''adm_my_files'';
  * Zugriff auf die konfigurierte Admidio-Datenbank.

Die CLI startet keine Browser-Session und benötigt keinen Webserver-Request.

Ein kleiner Satz von Befehlen steht absichtlich schon vor der Installation von Admidio zur Verfügung. Dadurch kann eine neue Installation vollständig über die Kommandozeile geprüft und angelegt werden:

<code bash>
./admidio help
./admidio list
./admidio completion
./admidio cli:selfcheck
./admidio install:check ...
./admidio install:run ...
</code>

Die Beispiele auf dieser Seite gehen davon aus, dass das aktuelle Verzeichnis das Admidio-Installationsverzeichnis ist.

===== CLI starten =====

Unter Linux und anderen Unix-ähnlichen Systemen kann das Skript ausführbar gemacht werden:

<code bash>
chmod +x admidio
./admidio version
</code>

Es kann auch immer ausdrücklich über PHP gestartet werden:

<code bash>
php ./admidio version
</code>

Unter Windows wird die PHP-Executable verwendet:

<code powershell>
php .\admidio version
</code>

Der Befehl kann auch mit einem absoluten Pfad aufgerufen werden. Für Cronjobs und andere Automatisierungen wird das empfohlen:

<code bash>
/usr/bin/php /var/www/admidio/admidio status
</code>

===== Allgemeine Syntax =====

Die allgemeine Syntax lautet:

<code>
admidio [global-options] COMMAND [arguments] [options]
</code>

Beispiel:

<code bash>
./admidio user:show john.doe --as=administrator --format=json
</code>

Ein Befehl besteht entweder aus einem einfachen Namen wie:

<code>
version
status
help
list
completion
</code>

oder aus Namespace und Aufgabe:

<code>
user:add
group:adduser
inventory:export
sso:list
</code>

Globale Optionen können vor oder nach dem Befehl stehen. Befehlsspezifische Optionen müssen nach dem Befehl stehen, weil die CLI sie erst kennt, nachdem der Befehl ermittelt wurde.

Beide Schreibweisen sind gültig:

<code bash>
./admidio --organization=club user:list --as=administrator --format=json
./admidio user:list --organization=club --as=administrator --format=json
</code>

Lange Optionen mit Wert akzeptieren sowohl ''--name=value'' als auch ''--name value''. In Skripten ist die Schreibweise mit ''='' meist eindeutiger.

Der Trenner ''--'' beendet die Optionsauswertung. Das ist nützlich, wenn ein Positionsargument selbst mit einem Bindestrich beginnt.

===== Hilfe anzeigen =====

Allgemeine Verwendung, globale Optionen und Exit-Codes anzeigen:

<code bash>
./admidio help
</code>

Die folgenden Kurzformen sind gleichwertig:

<code bash>
./admidio --help
./admidio -h
</code>

Alle registrierten Befehle auflisten:

<code bash>
./admidio list
</code>

Befehle eines Namespaces können separat aufgelistet werden:

<code bash>
./admidio list user
./admidio list inventory
./admidio list sso
</code>

Die Liste zeigt außerdem, ob ein Befehl ein Alias ist und ob er aktuell verfügbar ist.

Dokumentation für einen bestimmten Befehl anzeigen:

<code bash>
./admidio help group:adduser
</code>

Alternativ:

<code bash>
./admidio group:adduser --help
./admidio group:adduser -h
</code>

Namespaces und Tasks in der Registry anzeigen:

<code bash>
./admidio module:list
./admidio module:tasks
./admidio module:tasks inventory
</code>

Die vollständige, generierte Befehlsdokumentation wird ausgegeben mit:

<code bash>
./admidio help --all
</code>

Sie kann direkt als Markdown, DokuWiki oder JSON gerendert werden:

<code bash>
./admidio help --all --format=md
./admidio help --all --format=dokuwiki
./admidio help --all --format=json
</code>

Die [[en:2.0:cli:commands|CLI-Befehlsreferenz (Englisch)]] wird aus denselben Registry-Metadaten erzeugt, zum Beispiel:

<code bash>
./admidio help --all --format=dokuwiki --output=cli-commands.txt
</code>

Damit entspricht die generierte Seite der installierten Admidio-Version und enthält auch Befehle, die von Modulen registriert werden.

**Aktuelle Einschränkung:** Die generierten Befehlsmetadaten und damit auch die generierte CLI-Befehlsreferenz sind derzeit nur auf Englisch verfügbar. Dies ist eine bekannte Einschränkung der CLI. Übersetzte Übersichts- und Entwicklerseiten sollten bis zur Lokalisierung der CLI-Hilfe auf die englische Befehlsreferenz verlinken.

===== Globale Optionen =====

Die folgenden Optionen steuern die CLI selbst.

^ Option ^ Beschreibung ^
| ''--host=HOST'' | Wählt den Host, der beim Laden einer Installation verwendet wird, deren ''adm_my_files/config.php'' eine hostabhängige Konfiguration enthält. |
| ''--organization=ORG'' | Wählt die Admidio-Organisation anhand ihres Kurznamens. |
| ''--as=USER'' | Wählt den Admidio-Benutzer, dessen Berechtigungen und Audit-Identität für den Befehl verwendet werden. |
| ''--format=FORMAT'' | Wählt, sofern unterstützt, das Ausgabeformat. Die von einem bestimmten Befehl unterstützten Formate stehen in dessen Hilfe. |
| ''--output=FILE'' | Schreibt die Befehlsausgabe, sofern unterstützt, in eine Datei. |
| ''--quiet'' / ''-q'' | Unterdrückt menschenlesbare Erfolgsmeldungen. Angeforderte Daten, JSON-Ergebnisse und Fehler werden weiterhin ausgegeben. |
| ''--no-interaction'' | Verhindert interaktive Rückfragen des Befehls. |
| ''--yes'' / ''-y'' | Bestätigt destruktive oder ausdrücklich zu bestätigende Operationen ohne interaktive Nachfrage. |
| ''--help'' / ''-h'' | Zeigt die Hilfe für den ausgewählten Befehl. |

Nicht jede globale Ausgabeoption hat bei jedem Befehl eine sinnvolle Wirkung. Für Skripte sollte immer ''admidio help COMMAND'' für die konkrete Operation geprüft werden.

===== Ausführender Benutzer und Berechtigungen =====

Viele Befehle benötigen einen ausführenden Admidio-Benutzer:

<code>
--as=USER
</code>

''USER'' kann eine Benutzer-UUID, eine numerische Benutzer-ID oder ein eindeutiger Loginname sein.

Beispiel:

<code bash>
./admidio user:list --as=administrator
</code>

**Wichtig:** ''--as'' ist keine Anmeldung mit Passwort.

Die CLI ist eine lokale Administrationsschnittstelle. Eine Person oder ein Service-Account, der die CLI ausführen sowie Admidio-Konfiguration und Datenbank lesen kann, kann ein Admidio-Konto als ausführende Identität auswählen. Die Betriebssystemberechtigungen rund um die Admidio-Installation sind deshalb eine wichtige Sicherheitsgrenze.

Das ausgewählte Admidio-Konto muss trotzdem verwendbar sein. Ein ausführender Benutzer muss:

  * aktiviert sein;
  * aktives Mitglied der aktuellen Organisation sein.

Danach wendet Admidio das normale Berechtigungsmodell auf den Befehl an. Die genaue Prüfung hängt von der Operation ab:

  * Nur-lesende Befehle können verlangen, dass die zugehörige Komponente sichtbar ist, und wenden anschließend die normalen Sichtbarkeitsregeln auf Datensatzebene an;
  * ändernde Befehle erfordern normalerweise Administrationsrechte für die zugehörige Komponente;
  * einige Befehle verwenden speziellere Gruppen-/Mitglieder- oder Objektberechtigungen;
  * einige Operationen benötigen zusätzlich einen vollständigen Admidio-Administrator.

Zusätzliche deklarierte Anforderungen stehen gegebenenfalls in der befehlsspezifischen Hilfe.

Der ausführende Benutzer wird außerdem zum aktuellen Admidio-Benutzer für die normale Entity- und Changelog-Verarbeitung. CLI-Änderungen werden mit einem Ursprung wie diesem gekennzeichnet:

<code>
CLI: group:adduser
</code>

Verwende eine Administratoridentität nicht unnötig. Für automatisierte Aufgaben sollte ein aktiviertes Admidio-Konto mit genau den benötigten Rechten verwendet werden.

===== Organisation auswählen =====

Bei Installationen mit mehreren Organisationen:

<code bash>
./admidio --organization=club-a user:list --as=administrator
</code>

Der Wert ist der Admidio-Kurzname der Organisation.

Die Option ändert den Organisationskontext, bevor die CLI organisationsabhängige Admidio-Objekte und Einstellungen initialisiert.

Der mit ''--as'' gewählte ausführende Benutzer muss aktives Mitglied der ausgewählten Organisation sein.

===== Hostabhängige Konfigurationen =====

Einige Installationen verwenden ''$_SERVER['HTTP_HOST']'' in ''adm_my_files/config.php'', um unterschiedliche Datenbank- oder Umgebungseinstellungen auszuwählen.

Beim Start der CLI gibt es keinen HTTP-Request. Der gewünschte Host kann deshalb ausdrücklich angegeben werden:

<code bash>
./admidio --host=members.example.org status
</code>

Derselbe Wert kann über die Umgebungsvariable ''ADMIDIO_HOST'' gesetzt werden:

<code bash>
export ADMIDIO_HOST=members.example.org
./admidio status
</code>

Der Wert muss ein Hostname sein und darf optional einen Port enthalten, zum Beispiel:

<code>
members.example.org
members.example.org:8080
</code>

URL-Schema und Pfad dürfen nicht angegeben werden.

Diese Option wählt die Konfigurationsumgebung. Sie ist nicht der Hostname einer phpMyAdmin-Installation oder einer anderen Datenbank-Administrationsoberfläche.

===== Ausgabeformate =====

Verschiedene Befehle unterstützen unterschiedliche Ausgabeformate. Die befehlsspezifische Hilfe zeigt die für einen Befehl zulässigen Formate:

<code bash>
./admidio help sso:list
</code>

Von CLI-Befehlen verwendete Formate sind:

^ Format ^ Verwendungszweck ^
| ''text'' | Einfache menschenlesbare Ausgabe. |
| ''table'' | Tabellarische Terminalausgabe. Gut für kompakte Listen. |
| ''record'' | Ein Feld pro Zeile, einschließlich verschachtelter Werte. Gut für breite Datensätze und vollständige Objekte. |
| ''json'' | Strukturierte Ausgabe für Skripte und externe Anwendungen. |
| ''csv'' | Tabellarische Daten für Tabellenkalkulationen und andere Werkzeuge. |
| ''md'' | Markdown-Ausgabe, sofern unterstützt. |
| ''dokuwiki'' | Native DokuWiki-Syntax, sofern unterstützt. |

Nicht jeder Befehl unterstützt jedes Format.

Eine normale Tabelle eignet sich für kurze Listen:

<code bash>
./admidio sso:list --format=table --as=administrator
</code>

Für Objekte mit vielen Feldern ist ''record'' leichter lesbar:

<code bash>
./admidio sso:list --format=record --as=administrator
</code>

Beispiel:

<code>
type: saml
id: 2
uuid: 2b8618d0-...
client_id: intranet
name: Intranet SAML
enabled: yes

type: oidc
id: 3
uuid: 90c9777a-...
client_id: wiki
name: Wiki
enabled: yes
</code>

Für Skripte sollte möglichst JSON verwendet werden:

<code bash>
./admidio user:list --format=json --as=administrator
</code>

Wenn ''--format=json'' angegeben ist und die CLI fehlschlägt, wird auch der Fehler als strukturiertes JSON auf Standardfehler geschrieben. Ein Fehler enthält Fehlermeldung, Exception-Typ und Exit-Code. Automatisierungen müssen dadurch keine menschenlesbaren Fehlermeldungen parsen.

Ändernde Befehle, die nur eine Erfolgsbestätigung zurückgeben, liefern bei ''--format=json'' ebenfalls ein JSON-Objekt.

===== Ausgabe in eine Datei schreiben =====

Befehle mit normaler CLI-Ausgabe können diese direkt in eine Datei schreiben:

<code bash>
./admidio config:list --format=json --output=preferences.json --as=administrator
</code>

Befehle, die einen Export oder ein Backup erzeugen, verwenden ebenfalls ''--output''. Je nach Befehl kann der Wert ein ausdrücklicher Dateiname oder ein Zielverzeichnis für den natürlichen Dateinamen des Befehls sein.

Beispiel:

<code bash>
./admidio database:backup \
    --output=/srv/backups/admidio.sql.gz \
    --as=administrator
</code>

Vor der Verwendung von Ausgabepfaden in einem automatisierten Skript immer prüfen:

<code bash>
./admidio help COMMAND
</code>

===== Exit-Codes =====

Skripte sollten immer den Exit-Code des Prozesses auswerten.

^ Code ^ Bedeutung ^
| ''0'' | Der Befehl wurde erfolgreich beendet. |
| ''1'' | Interner CLI-Fehler, beispielsweise ein Datenbank- oder PHP-Fehler. |
| ''2'' | Aufruffehler: unbekannter Befehl, fehlendes Argument, ungültige Option oder ungültiger Wert. |
| ''3'' | Der Befehl wurde ausgeführt, aber der gemeldete Zustand ist nicht in Ordnung. Wird z. B. von ''status'', ''htaccess:status'' und bei einem fehlschlagenden ''cli:selfcheck'' verwendet. |
| ''4'' | Der Befehl wurde erfolgreich ausgeführt und eine neuere Admidio-Version ist verfügbar. Wird von ''update:check'' verwendet. |
| ''5'' | Admidio hat die Operation abgelehnt, z. B. wegen fehlender Rechte oder Domänenvalidierung. |
| ''6'' | Die Operation war gültig und zulässig, konnte aber nicht abgeschlossen werden. |

Nicht jeder von Null verschiedene Code bedeutet denselben Fehlertyp. Exit-Code ''4'' von ''update:check'' bedeutet beispielsweise: Die Prüfung war erfolgreich und ihr Ergebnis lautet "Ein Update ist verfügbar".

===== Admidio über die CLI installieren =====

Eine neue Admidio-Installation kann ohne Browser-Installer geprüft und angelegt werden.

Zuerst Datenbankverbindung, Installationswerte und Voraussetzungen prüfen:

<code bash>
./admidio install:check [options]
</code>

Anschließend die Installation ausführen:

<code bash>
./admidio install:run [options] --yes
</code>

Wenn Werte fehlen und Interaktion erlaubt ist, fragt die CLI danach. Mit ''--no-interaction'' müssen alle benötigten Werte als Optionen angegeben werden.

Ein typischer nicht-interaktiver Aufruf enthält:

  * Datenbanktyp, Host, Datenbankname und Datenbankbenutzer;
  * Datenbankpasswort, vorzugsweise über stdin;
  * Admidio-Root-URL;
  * Kurzname, Name und Administrator-E-Mail der Organisation;
  * Login, Vorname, Nachname, E-Mail und Passwort des Administrators;
  * optional Tabellenpräfix, Sprache und Zeitzone.

Beispiel:

<code bash>
{
    printf '%s\n' "$ADMIDIO_DB_PASSWORD"
    printf '%s\n' "$ADMIDIO_ADMIN_PASSWORD"
} | ./admidio install:run \
    --db-type=mariadb \
    --db-host=localhost \
    --db-name=admidio \
    --db-user=admidio \
    --db-password-stdin \
    --root-url=https://www.example.org/admidio \
    --timezone=Europe/Berlin \
    --organization-shortname=EXAMPLE \
    --organization-name="Example Organization" \
    --organization-email=info@example.org \
    --admin-login=admin \
    --admin-first-name=Anna \
    --admin-last-name=Admin \
    --admin-email=anna@example.org \
    --admin-password-stdin \
    --no-interaction \
    --yes
</code>

Wenn sowohl Datenbank- als auch Administratorpasswort aus stdin gelesen werden, steht das Datenbankpasswort in der ersten und das Administratorpasswort in der zweiten Zeile.

Bei der Bereitstellung einer Produktivinstallation sollte ''install:check'' zuerst mit denselben Werten ausgeführt werden.

===== Befehlsbereiche =====

Die generierte Befehlsreferenz ist die verbindliche Liste. Die CLI deckt derzeit insbesondere folgende Bereiche ab:

  * allgemeine Hilfe, Befehlsliste, Version/Status, Shell-Completion und CLI-Selbstprüfung;
  * Installation, Update-Prüfung, Systeminformationen, Datenbankbackup, E-Mail-Test, Schutz von ''adm_my_files'' und Wartung;
  * Einstellungen und Organisationen;
  * Benutzer, Registrierungen, Benutzerbeziehungen, Profilfelder, Gruppen, Mitgliedschaften, gespeicherte Listen und Berechtigungen;
  * Kategorien und Menüeinträge;
  * Ankündigungen, Foren, Links und Nachrichten;
  * Dokumente/Dateien und Fotoalben;
  * Inventarfelder, Inventargegenstände, Importe, Exporte sowie Ausleihe/Rückgabe;
  * Veranstaltungen und Räume;
  * Kategorieauswertungen und Changelog-Anzeige;
  * Plugins, SSO-Clients/-Schlüssel, Sessions und Auto-Login-Bereinigung;
  * Modul-/Namespace-Anzeige.

Die genauen Befehle eines Bereichs werden angezeigt mit:

<code bash>
./admidio list NAMESPACE
</code>

===== Häufige Administrationsbeispiele =====

==== Installationsversion und Status prüfen ====

<code bash>
./admidio version
./admidio status
</code>

''status'' vergleicht den Admidio-Quellstand mit der Core-Version in der Datenbank und meldet die aktuelle Organisation sowie den Datenbank-Updatezustand.

Wenn der Zustand nicht in Ordnung ist, wird Exit-Code ''3'' zurückgegeben.

Beispiel:

<code bash>
./admidio status --format=json > /tmp/admidio-status.json
code=$?

if [ "$code" -ne 0 ]; then
    echo "Admidio status requires attention (exit $code)." >&2
fi
</code>

Der Exit-Code sollte unmittelbar nach dem Befehl gespeichert werden, bevor ein weiterer Shell-Befehl ausgeführt wird.

==== Auf ein öffentliches Admidio-Update prüfen ====

<code bash>
./admidio update:check --as=administrator
</code>

Für Automatisierung:

<code bash>
./admidio update:check --format=json --as=administrator
</code>

Exit-Code ''4'' bedeutet, dass eine neuere Version verfügbar ist.

==== CLI-Selbstprüfung ausführen ====

Die CLI kann Registry, generierte Hilfe und interne Konsistenz ihres CLI-Quellcodes prüfen:

<code bash>
./admidio cli:selfcheck
</code>

Für CI oder andere Automatisierungen:

<code bash>
./admidio cli:selfcheck --format=json
</code>

Ein Problem wird mit Exit-Code ''3'' gemeldet.

Diese Selbstprüfung prüft die CLI-Infrastruktur. Sie ersetzt keine Verhaltenstests der zugrunde liegenden Admidio-Domänenoperationen.

==== Shell-Completion erzeugen ====

Bash- und Zsh-Completion-Skripte werden aus der Befehlsregistry erzeugt:

<code bash>
./admidio completion bash > /etc/bash_completion.d/admidio
</code>

oder:

<code bash>
./admidio completion zsh > "${fpath[1]}/_admidio"
</code>

Als nicht verfügbar registrierte Befehle werden nicht in die Completion aufgenommen.

==== Einstellungen lesen ====

Alle Einstellungen auflisten:

<code bash>
./admidio config:list --as=administrator
</code>

Nach Einstellungsnamen suchen:

<code bash>
./admidio config:list --filter=events --as=administrator
</code>

Einen Wert lesen:

<code bash>
./admidio config:get system_language --as=administrator
</code>

Einen Wert ändern:

<code bash>
./admidio config:set events_module_enabled 1 --as=administrator
</code>

Vor Änderungen per Skript sollten Einstellungsname und zulässiger Wert in der normalen Admidio-Konfiguration und in der Befehlshilfe geprüft werden.

==== Benutzer auflisten und anzeigen ====

<code bash>
./admidio user:list --as=administrator
./admidio user:show john.doe --as=administrator
</code>

Für ein gut lesbares vollständiges Objekt kann, sofern unterstützt, das Format ''record'' verwendet werden:

<code bash>
./admidio user:show john.doe --format=record --as=administrator
</code>

Für Automatisierungen JSON verwenden:

<code bash>
./admidio user:show john.doe --memberships --relations --format=json --as=administrator
</code>

==== Benutzer anlegen ====

Admidio-Profilfelder sind konfigurierbar. Benutzerdaten werden deshalb mit den internen Profilfeldnamen übergeben:

<code bash>
./admidio user:add \
    --login=john.doe \
    --field=FIRST_NAME=John \
    --field=LAST_NAME=Doe \
    --field=EMAIL=john@example.org \
    --as=administrator
</code>

Die konfigurierten Profilfelder können angezeigt werden mit:

<code bash>
./admidio profile:fields --as=administrator
</code>

Ein Benutzer kann direkt Gruppen zugeordnet werden:

<code bash>
./admidio user:add \
    --login=john.doe \
    --field=FIRST_NAME=John \
    --field=LAST_NAME=Doe \
    --group=Members \
    --as=administrator
</code>

Wenn ein Befehl ein Passwort oder ein anderes Geheimnis akzeptiert, sollte die jeweilige ''*-stdin''-Option verwendet werden, anstatt das Geheimnis in die Shell-History zu schreiben.

==== Gruppenmitgliedschaft ====

Vorhandenen Benutzer zuordnen:

<code bash>
./admidio group:adduser Members john.doe --as=administrator
</code>

Benutzer für einen definierten Zeitraum zuordnen:

<code bash>
./admidio group:adduser Board john.doe \
    --start=2026-09-01 \
    --end=2027-08-31 \
    --leader=yes \
    --as=administrator
</code>

Aktuelle Mitgliedschaft beenden:

<code bash>
./admidio group:deluser Board john.doe --as=administrator
</code>

Vorhandene Mitgliedschaft ändern:

<code bash>
./admidio group:updateuser Board john.doe \
    --leader=no \
    --as=administrator
</code>

Normale Mitgliedschaftsoperationen erhalten die Admidio-Mitgliedschaftshistorie.

Das dauerhafte Löschen eines Eintrags der Mitgliedschaftshistorie ist eine separate Operation:

<code bash>
./admidio group:deletemembership MEMBERSHIP_UUID --as=administrator
</code>

Sie benötigt eine Bestätigung und sollte nur bewusst verwendet werden.

==== Datenbankbackup ====

Datenbanksicherung erstellen:

<code bash>
./admidio database:backup --as=administrator
</code>

In ein bestimmtes Ziel schreiben:

<code bash>
./admidio database:backup \
    --output=/srv/backups/admidio.sql.gz \
    --as=administrator
</code>

Datenbank-Dumps enthalten die vollständigen Installationsdaten und werden, soweit das Betriebssystem dies erlaubt, als private Dateien geschützt.

Vor größeren skriptgesteuerten Änderungen oder Migrationen sollte ein Backup erstellt werden.

==== Inventar importieren und exportieren ====

Vor dem Import die aufgelöste Zuordnung prüfen, ohne Daten zu schreiben:

<code bash>
./admidio inventory:import-check ./inventory.xlsx \
    --format=json \
    --as=administrator
</code>

Inventardatei importieren:

<code bash>
./admidio inventory:import ./inventory.xlsx --as=administrator
</code>

Wenn Quellspalten nicht den konfigurierten Admidio-Inventarfeldern entsprechen, kann die Zuordnung ausdrücklich angegeben werden:

<code bash>
./admidio inventory:import ./inventory.csv \
    --input-format=CSV \
    --separator=semicolon \
    --map=ITEMNAME=1 \
    --map=CATEGORY=2 \
    --map=SERIAL_NUMBER=3 \
    --as=administrator
</code>

Inventardaten exportieren:

<code bash>
./admidio inventory:export \
    --format=xlsx \
    --output=inventory.xlsx \
    --as=administrator
</code>

Für die von der installierten Admidio-Version unterstützten Dateiformate und Optionen immer ''admidio help inventory:import'' bzw. ''admidio help inventory:export'' verwenden.

==== Veranstaltungen und Räume ====

Veranstaltungen und Räume können über ihre CLI-Befehlsfamilien administriert werden.

Beispiel zum Anlegen einer Veranstaltung:

<code bash>
./admidio event:add \
    --headline="Annual meeting" \
    --calendar=General \
    --from="2026-09-14T18:00" \
    --to="2026-09-14T20:00" \
    --location="Club house" \
    --as=administrator
</code>

Die genauen Veranstaltungs- und Raumoperationen sowie deren Optionen werden angezeigt mit:

<code bash>
./admidio list event
./admidio list room
</code>

und ''admidio help COMMAND''.

==== SSO-Administration ====

Alle SSO-Clients auflisten:

<code bash>
./admidio sso:list --format=record --as=administrator
</code>

Nur SAML-Clients anzeigen:

<code bash>
./admidio sso:list --type=saml --format=record --as=administrator
</code>

Einen Client anzeigen:

<code bash>
./admidio sso:show CLIENT_UUID --as=administrator
</code>

SSO-Schlüssel, SAML-Metadaten, OIDC-Discovery-Informationen und Token-Bereinigung können ebenfalls über die entsprechenden ''sso:*''-Befehle administriert werden.

Die vollständige Liste steht in der [[en:2.0:cli:commands|Befehlsreferenz (Englisch)]].

==== Wartungsmodus ====

Der Wartungsmodus kann auch abgefragt werden, wenn die Datenbank nicht verfügbar ist:

<code bash>
./admidio maintenance:mode
./admidio maintenance:mode status
</code>

Interaktiv aktivieren:

<code bash>
./admidio maintenance:mode enable \
    --message="Maintenance in progress" \
    --retry-after=300
</code>

Für eine bewusst nicht-interaktive Verwendung:

<code bash>
./admidio maintenance:mode enable \
    --message="Maintenance in progress" \
    --retry-after=300 \
    --no-interaction \
    --yes
</code>

Wartungsmodus deaktivieren:

<code bash>
./admidio maintenance:mode disable
</code>

Der Wartungsmodus besitzt eine Owner-Kennung, damit unabhängige Wartungsoperationen nicht unbemerkt den Zustand einer anderen Operation übernehmen. Vor der Verwendung von ''--owner'' oder ''--force'' in Automatisierungen die Befehlshilfe lesen.

===== CLI in Skripten verwenden =====

Die CLI ist für skriptgesteuerte Verwendung ausgelegt.

Für zuverlässige Automatisierungen:

  * absolute Pfade verwenden;
  * bei Installationen mit mehreren Organisationen die Organisation ausdrücklich auswählen;
  * einen eigenen aktivierten Admidio-Akteur mit nur den benötigten Rechten verwenden;
  * ''--no-interaction'' verwenden;
  * ''--yes'' nur verwenden, wenn das Skript eine destruktive bzw. bestätigungspflichtige Aktion bewusst akzeptiert;
  * wenn möglich UUIDs für langlebige Objektreferenzen verwenden;
  * ''--format=json'' für maschinenlesbare Ausgabe verwenden;
  * Standardausgabe für Daten und Standardfehler für Fehler auswerten;
  * den Prozess-Exit-Code auswerten;
  * für Passwörter und Geheimnisse verfügbare ''*-stdin''-Optionen verwenden;
  * in Integrationen keine Tabellen-/Textausgabe parsen.

==== Bash-Beispiel ====

<code bash>
#!/bin/sh

ADMIDIO=/var/www/admidio/admidio
ACTOR=automation-admin

"$ADMIDIO" status --format=json --output=/tmp/admidio-status.json
status_code=$?

if [ "$status_code" -ne 0 ]; then
    echo "Admidio installation requires attention (exit $status_code)." >&2
    exit "$status_code"
fi

"$ADMIDIO" group:members Members \
    --format=json \
    --as="$ACTOR" \
    --no-interaction \
    --output=/tmp/admidio-members.json
</code>

==== PowerShell-Beispiel ====

<code powershell>
$Admidio = "C:\inetpub\wwwroot\admidio\admidio"

$statusJson = php $Admidio status --format=json
$statusCode = $LASTEXITCODE

if ($statusCode -ne 0) {
    Write-Error "Admidio installation requires attention (exit $statusCode)."
    exit $statusCode
}

$status = $statusJson | ConvertFrom-Json

$users = php $Admidio user:list `
    --format=json `
    --as=automation-admin | ConvertFrom-Json

$users | ForEach-Object {
    Write-Host $_.login
}
</code>

===== Geplante Aufgaben =====

Für Cronjobs die CLI mit absolutem Pfad aufrufen und Interaktion deaktivieren.

Beispiel:

<code>
15 2 * * * /usr/bin/php /var/www/admidio/admidio database:backup --output=/srv/backups/admidio.sql.gz --as=backup-admin --no-interaction
</code>

Der Betriebssystembenutzer, der die geplante Aufgabe ausführt, benötigt Zugriff auf:

  * die Admidio-Installation;
  * ''adm_my_files'';
  * alle von der Aufgabe verwendeten Ein-/Ausgabedateien;
  * die konfigurierte Datenbank.

Außerdem muss das mit ''--as'' verwendete Admidio-Konto aktiviert und aktives Mitglied der ausgewählten Organisation bleiben.

===== Andere Anwendungen integrieren =====

Die CLI kann als administrative Grenze zwischen einer anderen Anwendung bzw. einem Migrationsskript und Admidio verwendet werden.

Anstatt direkt in die Admidio-Datenbank zu schreiben, kann eine Integration den passenden Admidio-Befehl aufrufen.

Ein externes Provisioning-Skript kann zum Beispiel:

  - mit ''user:add'' einen Benutzer anlegen;
  - mit ''user:update'' Profilfelder ändern;
  - mit ''group:adduser'' den Benutzer einer Gruppe zuordnen;
  - mit ''group:deluser'' eine Mitgliedschaft beenden;
  - das Ergebnis mit ''user:show --format=json'' prüfen.

Das hat gegenüber direktem SQL einen wichtigen Vorteil: Der Befehl verwendet die normalen Admidio-Entities, Services, Berechtigungen, Changelog- und Folgelogik.

==== Beispiel für einen Migrationsablauf ====

Eine typische Migration aus einem anderen Mitgliederverwaltungssystem kann so ablaufen:

  - Datenbankbackup erstellen;
  - benötigte Admidio-Gruppen anlegen oder zuordnen;
  - konfigurierte Profilfelder mit ''profile:fields'' anzeigen;
  - Quelldaten auf die benötigten internen Feldnamen abbilden;
  - für jede Person ''user:add'' oder ''user:update'' aufrufen;
  - mit ''group:adduser'' Mitgliedschaften einschließlich Start-/Enddatum wiederherstellen;
  - Ergebnis mit ''user:list'', ''group:members'' und JSON-Exporten vergleichen.

Größere Migrationen zuerst vollständig gegen eine Kopie der Produktivinstallation testen.

===== Bezeichner in Skripten auswählen =====

Viele Befehle akzeptieren für ein Objekt mehrere Bezeichner, zum Beispiel:

  * UUID;
  * numerische Datenbank-ID;
  * Loginname;
  * Gruppen- oder Kategoriename.

Für interaktive Administration sind Namen bequem:

<code bash>
./admidio group:adduser Board john.doe --as=administrator
</code>

Für langlebige Integrationen sollten UUIDs bevorzugt werden, sofern der jeweilige Befehl sie akzeptiert.

Namen können geändert werden und manchmal mehrdeutig sein. Ist ein Selektor mehrdeutig, schlägt die CLI fehl, anstatt stillschweigend ein Objekt auszuwählen.

===== Interaktive und nicht-interaktive Befehle =====

Bestätigungspflichtige Befehle fragen standardmäßig interaktiv nach.

Beispiel:

<code bash>
./admidio group:delete OldGroup --as=administrator
</code>

Für eine bewusst automatisierte Operation:

<code bash>
./admidio group:delete OldGroup \
    --as=administrator \
    --no-interaction \
    --yes
</code>

Wenn eine Bestätigung nötig wäre und ''--no-interaction'' ohne ''--yes'' gesetzt ist, schlägt der Befehl fehl, anstatt stillschweigend fortzufahren.

''--yes'' sollte nicht pauschal jedem automatisierten Befehl hinzugefügt werden. Die Option soll ausdrücken, dass das Skript die Operation bewusst akzeptiert.

===== Verfügbarkeit registrierter Befehle =====

Ein Befehl kann in der Registry vorhanden, aber als nicht verfügbar markiert sein, wenn die entsprechende Webfunktion noch keine wiederverwendbare headless Operation besitzt.

''admidio list'' zeigt diesen Zustand; ''admidio help COMMAND'' enthält einen Verfügbarkeitshinweis.

Die Shell-Completion lässt als nicht verfügbar markierte Befehle aus.

Ein nicht verfügbarer Befehl sollte nicht durch direkte Manipulation der Admidio-Datenbank umgangen werden. Verwende die entsprechende unterstützte Webfunktion oder warte, bis die benötigte wiederverwendbare Core-Operation verfügbar ist.

===== Fehlerbehebung =====

==== Die CLI verbindet sich mit der falschen Datenbank ====

Die CLI lädt ''adm_my_files/config.php'' der Admidio-Installation.

Wenn die Konfiguration anhand von ''HTTP_HOST'' eine Umgebung auswählt, den erwarteten Host angeben:

<code bash>
./admidio --host=members.example.org status
</code>

oder setzen:

<code bash>
ADMIDIO_HOST=members.example.org
</code>

==== Der Befehl meldet, dass --as benötigt wird ====

Der gewählte Befehl benötigt eine ausführende Admidio-Identität.

Einen aktivierten Benutzer angeben, der aktives Mitglied der aktuellen Organisation ist:

<code bash>
./admidio COMMAND --as=administrator
</code>

''--as'' wählt eine Identität aus; es führt keine Passwortanmeldung durch.

==== Das ausführende Konto ist nicht aktiviert oder kein aktives Mitglied ====

Ein mit ''--as'' verwendetes Konto muss aktiviert sein und aktuell zur ausgewählten Organisation gehören.

Das Konto über die normale Admidio-Administration aktivieren bzw. zuordnen, bevor es als Automatisierungs-Akteur verwendet wird.

==== Keine Berechtigung / SYS_NO_RIGHTS ====

Die CLI umgeht Admidio-Berechtigungen nicht.

Prüfen:

  * ausgewählte Organisation;
  * ausführender Benutzer;
  * ob die betreffende Komponente für den Benutzer sichtbar/administrierbar ist;
  * objektspezifische oder Gruppen-/Mitgliederrechte der Operation;
  * ob der Befehl einen vollständigen Administrator benötigt.

==== Ein Name ist mehrdeutig ====

Die UUID aus dem entsprechenden ''list''- oder ''show''-Befehl verwenden.

==== Ein Ausgabeformat wird abgelehnt ====

Nicht jedes Format ist für jeden Befehl gültig.

Mit:

<code bash>
./admidio help COMMAND
</code>

die genauen zulässigen Werte anzeigen.

==== Ein Befehl wird als nicht verfügbar angezeigt ====

Die Verfügbarkeitserklärung anzeigen mit:

<code bash>
./admidio help COMMAND
</code>

Die Registry zeigt den Grund bewusst an, anstatt stillschweigend eine unvollständige headless Implementierung anzubieten.

==== Befehle eines Moduls fehlen ====

Modulbefehle werden geladen aus:

<code>
modules/<module>/cli.php
</code>

Schlägt das Laden der CLI-Registrierung eines Moduls fehl, schreibt die CLI eine Warnung auf Standardfehler und lädt die übrigen Befehle weiter. Die Warnung prüfen und anschließend ausführen:

<code bash>
./admidio module:tasks
</code>

um die erfolgreich registrierten Befehle zu sehen.

===== Sicherheitsempfehlungen =====

Die CLI sollte als administrative Serverschnittstelle behandelt werden.

  * Shellzugriff auf vertrauenswürdige Benutzer und Service-Accounts beschränken.
  * Admidio-Quellbaum und ''adm_my_files'' mit geeigneten Dateisystemberechtigungen schützen.
  * Die CLI nicht über einen webzugänglichen Wrapper bereitstellen.
  * Beachten, dass ''--as'' Impersonation und keine Authentifizierung ist.
  * Für automatisierte Aufgaben gegebenenfalls einen eigenen aktivierten Admidio-Akteur verwenden.
  * Diesem Akteur nur die für die Automatisierung benötigten Rechte geben.
  * Vor Massenänderungen Backups erstellen.
  * Wo unterstützt, Geheimnisse über stdin einlesen.
  * Passwörter, private Schlüssel und andere Geheimnisse nicht direkt in Shellskripten oder Shell-History speichern.
  * Erzeugte Backups und geheime Exporte schützen.
  * Für langlebige Integrationsskripte UUIDs bevorzugen.
  * JSON verwenden, statt menschenlesbare Tabellenausgabe zu parsen.
  * Exit-Codes auswerten und stderr nicht ignorieren.

===== Befehlsreferenz =====

Die vollständige Befehlsreferenz wird direkt aus der installierten CLI erzeugt:

<code bash>
./admidio help --all --format=dokuwiki
</code>

Eine Datei für die DokuWiki-Seite kann so erzeugt werden:

<code bash>
./admidio help --all --format=dokuwiki --output=cli-commands.txt
</code>

Siehe [[en:2.0:cli:commands|CLI-Befehlsreferenz (Englisch)]].

Da diese Seite direkt aus der Befehlsregistry erzeugt wird, ist sie die verbindliche Beschreibung von Argumenten, Optionen, Aliasnamen, zusätzlich deklarierten Rechten und Verfügbarkeit einer bestimmten Admidio-Version.

Die generierte Befehlsreferenz ist derzeit nur auf Englisch verfügbar, weil die CLI-Hilfemetadaten noch nicht lokalisiert werden.