no way to compare when less than two revisions

Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.


—de:2.0:cli:usage [2026/08/23 00:27] (aktuell) – angelegt kainhofer
Zeile 1: Zeile 1:
 +====== 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.
  
  • de/2.0/cli/usage.txt
  • Zuletzt geändert: 2026/08/23 00:27
  • von kainhofer