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:

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

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 CLI-Befehlsreferenz (Englisch).

Entwickler, die einem Admidio-Modul zusätzliche CLI-Befehle hinzufügen möchten, finden weitere Informationen unter CLI-Befehle zu Admidio-Modulen hinzufügen.

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:

./admidio help
./admidio list
./admidio completion
./admidio cli:selfcheck
./admidio install:check ...
./admidio install:run ...

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

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

chmod +x admidio
./admidio version

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

php ./admidio version

Unter Windows wird die PHP-Executable verwendet:

php .\admidio version

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

/usr/bin/php /var/www/admidio/admidio status

Die allgemeine Syntax lautet:

admidio [global-options] COMMAND [arguments] [options]

Beispiel:

./admidio user:show john.doe --as=administrator --format=json

Ein Befehl besteht entweder aus einem einfachen Namen wie:

version
status
help
list
completion

oder aus Namespace und Aufgabe:

user:add
group:adduser
inventory:export
sso:list

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:

./admidio --organization=club user:list --as=administrator --format=json
./admidio user:list --organization=club --as=administrator --format=json

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.

Allgemeine Verwendung, globale Optionen und Exit-Codes anzeigen:

./admidio help

Die folgenden Kurzformen sind gleichwertig:

./admidio --help
./admidio -h

Alle registrierten Befehle auflisten:

./admidio list

Befehle eines Namespaces können separat aufgelistet werden:

./admidio list user
./admidio list inventory
./admidio list sso

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:

./admidio help group:adduser

Alternativ:

./admidio group:adduser --help
./admidio group:adduser -h

Namespaces und Tasks in der Registry anzeigen:

./admidio module:list
./admidio module:tasks
./admidio module:tasks inventory

Die vollständige, generierte Befehlsdokumentation wird ausgegeben mit:

./admidio help --all

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

./admidio help --all --format=md
./admidio help --all --format=dokuwiki
./admidio help --all --format=json

Die CLI-Befehlsreferenz (Englisch) wird aus denselben Registry-Metadaten erzeugt, zum Beispiel:

./admidio help --all --format=dokuwiki --output=cli-commands.txt

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.

Die folgenden Optionen steuern die CLI selbst.

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.

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

--as=USER

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

Beispiel:

./admidio user:list --as=administrator

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:

CLI: group:adduser

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

Bei Installationen mit mehreren Organisationen:

./admidio --organization=club-a user:list --as=administrator

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.

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:

./admidio --host=members.example.org status

Derselbe Wert kann über die Umgebungsvariable ADMIDIO_HOST gesetzt werden:

export ADMIDIO_HOST=members.example.org
./admidio status

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

members.example.org
members.example.org:8080

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.

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

./admidio help sso:list

Von CLI-Befehlen verwendete Formate sind:

Nicht jeder Befehl unterstützt jedes Format.

Eine normale Tabelle eignet sich für kurze Listen:

./admidio sso:list --format=table --as=administrator

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

./admidio sso:list --format=record --as=administrator

Beispiel:

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

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

./admidio user:list --format=json --as=administrator

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.

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

./admidio config:list --format=json --output=preferences.json --as=administrator

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:

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

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

./admidio help COMMAND

Skripte sollten immer den Exit-Code des Prozesses auswerten.

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“.

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

Zuerst Datenbankverbindung, Installationswerte und Voraussetzungen prüfen:

./admidio install:check [options]

Anschließend die Installation ausführen:

./admidio install:run [options] --yes

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:

{
    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

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.

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:

./admidio list NAMESPACE

./admidio version
./admidio status

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:

./admidio status --format=json > /tmp/admidio-status.json
code=$?
 
if [ "$code" -ne 0 ]; then
    echo "Admidio status requires attention (exit $code)." >&2
fi

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

./admidio update:check --as=administrator

Für Automatisierung:

./admidio update:check --format=json --as=administrator

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

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

./admidio cli:selfcheck

Für CI oder andere Automatisierungen:

./admidio cli:selfcheck --format=json

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.

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

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

oder:

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

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

Alle Einstellungen auflisten:

./admidio config:list --as=administrator

Nach Einstellungsnamen suchen:

./admidio config:list --filter=events --as=administrator

Einen Wert lesen:

./admidio config:get system_language --as=administrator

Einen Wert ändern:

./admidio config:set events_module_enabled 1 --as=administrator

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

./admidio user:list --as=administrator
./admidio user:show john.doe --as=administrator

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

./admidio user:show john.doe --format=record --as=administrator

Für Automatisierungen JSON verwenden:

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

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

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

Die konfigurierten Profilfelder können angezeigt werden mit:

./admidio profile:fields --as=administrator

Ein Benutzer kann direkt Gruppen zugeordnet werden:

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

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.

Vorhandenen Benutzer zuordnen:

./admidio group:adduser Members john.doe --as=administrator

Benutzer für einen definierten Zeitraum zuordnen:

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

Aktuelle Mitgliedschaft beenden:

./admidio group:deluser Board john.doe --as=administrator

Vorhandene Mitgliedschaft ändern:

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

Normale Mitgliedschaftsoperationen erhalten die Admidio-Mitgliedschaftshistorie.

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

./admidio group:deletemembership MEMBERSHIP_UUID --as=administrator

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

Datenbanksicherung erstellen:

./admidio database:backup --as=administrator

In ein bestimmtes Ziel schreiben:

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

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.

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

./admidio inventory:import-check ./inventory.xlsx \
    --format=json \
    --as=administrator

Inventardatei importieren:

./admidio inventory:import ./inventory.xlsx --as=administrator

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

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

Inventardaten exportieren:

./admidio inventory:export \
    --format=xlsx \
    --output=inventory.xlsx \
    --as=administrator

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 können über ihre CLI-Befehlsfamilien administriert werden.

Beispiel zum Anlegen einer Veranstaltung:

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

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

./admidio list event
./admidio list room

und admidio help COMMAND.

Alle SSO-Clients auflisten:

./admidio sso:list --format=record --as=administrator

Nur SAML-Clients anzeigen:

./admidio sso:list --type=saml --format=record --as=administrator

Einen Client anzeigen:

./admidio sso:show CLIENT_UUID --as=administrator

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 Befehlsreferenz (Englisch).

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

./admidio maintenance:mode
./admidio maintenance:mode status

Interaktiv aktivieren:

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

Für eine bewusst nicht-interaktive Verwendung:

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

Wartungsmodus deaktivieren:

./admidio maintenance:mode disable

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.

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.

#!/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

$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
}

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

Beispiel:

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

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.

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:

1. mit user:add einen Benutzer anlegen;
2. mit user:update Profilfelder ändern;
3. mit group:adduser den Benutzer einer Gruppe zuordnen;
4. mit group:deluser eine Mitgliedschaft beenden;
5. 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.

Eine typische Migration aus einem anderen Mitgliederverwaltungssystem kann so ablaufen:

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

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

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:

./admidio group:adduser Board john.doe --as=administrator

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.

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

Beispiel:

./admidio group:delete OldGroup --as=administrator

Für eine bewusst automatisierte Operation:

./admidio group:delete OldGroup \
    --as=administrator \
    --no-interaction \
    --yes

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.

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.

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:

./admidio --host=members.example.org status

oder setzen:

ADMIDIO_HOST=members.example.org

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

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

./admidio COMMAND --as=administrator

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

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.

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.

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

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

Mit:

./admidio help COMMAND

die genauen zulässigen Werte anzeigen.

Die Verfügbarkeitserklärung anzeigen mit:

./admidio help COMMAND

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

Modulbefehle werden geladen aus:

modules/<module>/cli.php

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:

./admidio module:tasks

um die erfolgreich registrierten Befehle zu sehen.

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.

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

./admidio help --all --format=dokuwiki

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

./admidio help --all --format=dokuwiki --output=cli-commands.txt

Siehe 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.