====== Admidio command-line interface ======
 
The Admidio command-line interface (CLI) provides a scriptable administrative interface to Admidio directly from a shell.

The executable is located in the top-level Admidio directory and is called ''admidio''. It is executed from a shell in the Admidio installation directory:
<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>



The CLI uses the same Admidio entities, services, permissions, organization context and database as the web application. It is therefore suitable both for interactive administration and for automation without duplicating Admidio business logic in external scripts.

Typical use cases include:

  * checking the Admidio version, installation status and update availability;
  * installing Admidio without using the browser-based installer;
  * reading and changing organization preferences;
  * creating, inspecting and maintaining users, groups, memberships, lists and permissions;
  * maintaining registrations, user relations and profile fields;
  * maintaining categories, menus, announcements, forums, links and messages;
  * importing, exporting and maintaining inventory data;
  * maintaining events and rooms;
  * working with documents, files and photo albums;
  * inspecting changelog and category-report data;
  * administering plugins, SSO clients and SSO keys;
  * invalidating and cleaning sessions and auto-login data;
  * creating database backups and running maintenance operations;
  * using Admidio from maintenance scripts, cron jobs and deployment systems;
  * connecting other applications to Admidio through a scriptable administrative interface.

For the exact list of commands, arguments and command-specific options see the [[en:2.0:cli:commands|CLI command reference]].

Developers who want to add CLI commands to an Admidio module should see [[en:entwickler:cli|Adding CLI commands to Admidio modules]].

===== Requirements and bootstrap =====

Most commands operate on an existing Admidio installation. For those commands you need:

  * an installed Admidio instance;
  * PHP CLI;
  * the PHP extensions required by that Admidio installation;
  * filesystem access to the Admidio directory and ''adm_my_files'';
  * access to the configured Admidio database.

The CLI does not start a browser session and does not require a web server request.

A small set of commands is deliberately available before Admidio has been installed. This allows a new installation to be inspected and created entirely from the command line:

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

The examples on this page assume that the current directory is the Admidio installation directory.

===== Starting the CLI =====

On Linux and other Unix-like systems the script can be made executable:

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

It can also always be started explicitly through PHP:

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

On Windows, use the PHP executable:

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

The command can also be called using an absolute path. This is recommended for cron jobs and other automation:

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

===== General syntax =====

The general syntax is:

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

For example:

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

A command consists either of a simple name such as:

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

or a namespace and task:

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

Global options can be placed before or after the command. Command-specific options must be placed after the command because the CLI cannot know them before it has identified the command.

Both of these forms are valid:

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

Long options that take a value accept both ''--name=value'' and ''--name value''. The ''='' form is usually clearer in scripts.

The separator ''--'' stops option parsing. This is useful when a positional argument itself begins with a hyphen.

===== Getting help =====

To display the general usage, global options and exit codes:

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

The following are equivalent shortcuts:

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

To list all registered commands:

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

Commands of one namespace can be listed separately:

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

The list also shows whether a command is an alias and whether it is currently available.

To show the documentation for a specific command:

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

You can also use:

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

To inspect the namespaces and tasks represented in the registry:

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

The complete generated command documentation is available with:

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

It can be rendered directly as Markdown, DokuWiki or JSON:

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

The [[en:2.0:cli:commands|CLI command reference]] is generated from the same registry metadata, for example:

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

Therefore the generated page should correspond to the installed Admidio version, including commands supplied by modules.

**Current limitation:** the generated command metadata and therefore the generated CLI command reference are currently available in English only. This is a known CLI limitation. Translated overview/developer pages should link to the English command reference until CLI help localization is implemented.

===== Global options =====

The following options control the CLI itself.

^ Option ^ Description ^
| ''--host=HOST'' | Selects the host used while loading an installation whose ''adm_my_files/config.php'' contains host-dependent configuration. |
| ''--organization=ORG'' | Selects the Admidio organization by its short name. |
| ''--as=USER'' | Selects the Admidio user whose permissions and audit identity are used for the command. |
| ''--format=FORMAT'' | Selects an output format where supported. The formats supported by a particular command are listed in its help. |
| ''--output=FILE'' | Writes command output to a file where supported. |
| ''--quiet'' / ''-q'' | Suppresses human-readable success confirmations. Requested data, JSON results and errors are still emitted. |
| ''--no-interaction'' | Prevents the command from asking interactive questions. |
| ''--yes'' / ''-y'' | Confirms destructive or otherwise explicitly confirmed operations without asking interactively. |
| ''--help'' / ''-h'' | Displays help for the selected command. |

Not every global output option has a meaningful effect for every command. Always use ''admidio help COMMAND'' when scripting a specific operation.

===== The acting user and permissions =====

Many commands require an acting Admidio user:

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

''USER'' can be a user UUID, numeric user ID or unique login name.

For example:

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

**Important:** ''--as'' is not a password login.

The CLI is a local administrative interface. A person or service account that can execute the CLI and read the Admidio configuration/database can select an Admidio account as the acting identity. Operating-system permissions around the Admidio installation are therefore an important security boundary.

The selected Admidio account must nevertheless be usable. An acting user must:

  * be activated;
  * be an active member of the current organization.

Admidio then applies the normal authorization model to the command. The exact check depends on the operation:

  * read-only commands can require that the corresponding component is visible and then apply the normal record-level visibility rules;
  * mutating commands normally require administration rights for the corresponding component;
  * some commands use more specific group/member or object rights;
  * some operations additionally require a full Admidio administrator.

The command-specific help states additional declared requirements where applicable.

The acting user also becomes the current Admidio user for normal entity and changelog processing. CLI changes are marked with an origin such as:

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

Do not use an administrator identity unnecessarily. For automated tasks, use an activated Admidio account with only the permissions required by the task.

===== Selecting an organization =====

For installations with several organizations, use:

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

The value is the organization's Admidio short name.

The option changes the organization context before the CLI initializes organization-dependent Admidio objects and preferences.

The acting user selected with ''--as'' must be an active member of the selected organization.

===== Host-dependent configurations =====

Some installations use ''$_SERVER['HTTP_HOST']'' in ''adm_my_files/config.php'' to select different database or environment settings.

There is no HTTP request when the CLI starts, so the desired host can be supplied explicitly:

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

The same value can be supplied through the environment variable ''ADMIDIO_HOST'':

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

The value must be a host name, optionally including a port, for example:

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

Do not include a URL scheme or path.

This option selects the configuration environment. It is not the hostname of a phpMyAdmin installation or another database administration interface.

===== Output formats =====

Different commands support different output formats. Use command-specific help to see the exact formats accepted by a command:

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

Formats used by CLI commands include:

^ Format ^ Intended use ^
| ''text'' | Simple human-readable output. |
| ''table'' | Tabular terminal output. Best for compact lists. |
| ''record'' | One field per line, including nested values. Best for wide records and complete entities. |
| ''json'' | Structured output for scripts and external applications. |
| ''csv'' | Tabular data for spreadsheets and other tools. |
| ''md'' | Markdown output where supported. |
| ''dokuwiki'' | Native DokuWiki markup where supported. |

Not every command supports every format.

A normal table is useful for short lists:

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

For objects with many fields, the ''record'' format is easier to read:

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

Example:

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

For scripts, use JSON wherever possible:

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

If ''--format=json'' is present and the CLI fails, the error is also written as structured JSON to standard error. A failure contains the error message, exception type and exit code. This makes it possible for automation to handle errors without parsing human-readable text.

Mutating commands that only have a success confirmation also return a JSON object when ''--format=json'' is requested.

===== Writing output to a file =====

Commands using normal CLI output can write it directly to a file:

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

Commands that generate an export or backup also use ''--output''. Depending on the command, the value can be an explicit filename or a destination directory for the command's natural filename.

For example:

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

Always check:

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

before using output paths in an automated script.

===== Exit codes =====

Scripts should always inspect the process exit code.

^ Code ^ Meaning ^
| ''0'' | The command finished successfully. |
| ''1'' | Internal CLI error, for example a database failure or PHP error. |
| ''2'' | Usage error: unknown command, missing argument, invalid option or invalid value. |
| ''3'' | The command ran, but the state it reports is not OK. Used for checks such as ''status'', ''htaccess:status'' and a failing ''cli:selfcheck''. |
| ''4'' | The command ran successfully and a newer Admidio release is available. Used by ''update:check''. |
| ''5'' | Admidio rejected the operation, for example because of missing rights or domain validation. |
| ''6'' | The operation was valid and permitted but could not be completed. |

Do not treat every non-zero code as the same type of failure. For example, exit code ''4'' from ''update:check'' is a successful check whose result is "an update is available".

===== Installing Admidio from the CLI =====

A new Admidio installation can be checked and created without opening the browser installer.

First validate the database connection, installation values and prerequisites:

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

Then run the installation:

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

If values are missing and interaction is allowed, the CLI asks for them. With ''--no-interaction'', every required value must be provided as an option.

A typical non-interactive invocation provides:

  * database type, host, database name and database user;
  * database password, preferably through stdin;
  * Admidio root URL;
  * organization short name, name and administrator email;
  * administrator login, first name, last name, email and password;
  * optional table prefix, language and timezone.

For example:

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

When both database and administrator passwords are read from stdin, the database password is the first line and the administrator password is the second line.

Run ''install:check'' with the same values first when provisioning a production installation.

===== Command areas =====

The generated command reference is the authoritative list, but the CLI currently covers the following main areas:

  * general help, command listing, version/status, shell completion and CLI self-check;
  * installation, update checks, system information, database backup, email test, ''adm_my_files'' protection and maintenance;
  * preferences and organizations;
  * users, registrations, user relations, profile fields, groups, memberships, saved lists and permissions;
  * categories and menu entries;
  * announcements, forums, links and messages;
  * documents/files and photo albums;
  * inventory fields, items, imports, exports and checkout/return operations;
  * events and rooms;
  * category reports and changelog inspection;
  * plugins, SSO clients/keys, sessions and auto-login cleanup;
  * module/namespace inspection.

Use:

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

to see the exact commands in one area.

===== Common administrative examples =====

==== Check the installation version and status ====

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

''status'' compares the Admidio source with the database core version and reports the current organization and database update state.

It returns exit code ''3'' if the state is not OK.

Example:

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

Capture the exit code immediately after the command before running another shell command.

==== Check for a public Admidio update ====

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

For automation:

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

Exit code ''4'' means that a newer release is available.

==== Run the CLI self-check ====

The CLI can validate its registry, generated help and internal CLI source consistency:

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

For CI or other automation:

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

A problem is reported with exit code ''3''.

This self-check validates the CLI infrastructure. It does not replace behavioral tests of the underlying Admidio domain operations.

==== Generate shell completion ====

Bash and Zsh completion scripts can be generated from the command registry:

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

or:

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

Commands that are registered as unavailable are omitted from completion.

==== Read preferences ====

List all preferences:

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

Search preference names:

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

Read one value:

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

Change one value:

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

Before changing preferences through scripts, verify the setting name and accepted value in the normal Admidio configuration and command help.

==== List and inspect users ====

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

Use the ''record'' format for a readable full object where that format is supported:

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

Use JSON for automation:

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

==== Create a user ====

Admidio profile fields are configurable. User data is therefore supplied using the internal profile-field names:

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

The configured profile fields can be inspected with:

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

A user can immediately be assigned to groups:

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

If a command accepts a password or another secret, prefer its ''*-stdin'' option over putting the secret in shell history.

==== Group membership ====

Assign an existing user:

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

Assign the user for a defined period:

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

End the current membership:

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

Update an existing membership:

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

Normal membership operations preserve Admidio's membership history.

Permanent deletion of a membership-history row is a separate operation:

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

It requires confirmation and should only be used deliberately.

==== Database backup ====

Create a database backup:

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

Write it to a specific destination:

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

Database dumps contain the complete installation data and are protected as private files where the operating system permits it.

Take a backup before larger scripted changes or migrations.

==== Inventory import and export ====

Before importing, preview the resolved mapping without writing data:

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

Import an inventory file:

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

The importer supports explicit mapping when source columns do not correspond to the configured Admidio inventory fields:

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

Export inventory data:

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

Always use ''admidio help inventory:import'' or ''admidio help inventory:export'' for the exact file formats and options supported by your installed Admidio version.

==== Events and rooms ====

Events and rooms can be administered through their CLI command families.

For example, creating an event:

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

Use:

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

and ''admidio help COMMAND'' for the exact event and room operations and options of the installed version.

==== SSO administration ====

List all SSO clients:

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

Show only SAML clients:

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

Inspect one client:

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

SSO keys, SAML metadata, OIDC discovery information and token cleanup can also be administered through the corresponding ''sso:*'' commands.

See the [[en:2.0:cli:commands|command reference]] for the full list.

==== Maintenance mode ====

The maintenance switch can be queried even when the database is unavailable:

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

Enable it interactively:

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

For deliberate non-interactive use:

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

Disable maintenance mode:

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

Maintenance mode has an owner identifier so independent maintenance operations do not silently take over each other's state. Use command help before using ''--owner'' or ''--force'' in automation.

===== Using the CLI from scripts =====

The CLI is designed to be scriptable.

For reliable automation:

  * use absolute paths;
  * select the organization explicitly when an installation contains several organizations;
  * use a dedicated activated Admidio actor with only the required rights;
  * use ''--no-interaction'';
  * use ''--yes'' only when a destructive or confirmed action is deliberately accepted by the script;
  * use UUIDs for long-lived object references where possible;
  * use ''--format=json'' for machine-readable output;
  * parse standard output for data and standard error for errors;
  * inspect the process exit code;
  * use ''*-stdin'' options for passwords and secrets when available;
  * avoid parsing table/text output in integrations.

==== Bash example ====

<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 example ====

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

===== Scheduled jobs =====

For cron jobs, call the CLI by absolute path and disable interaction.

Example:

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

Make sure that the operating-system user running the scheduled task has access to:

  * the Admidio installation;
  * ''adm_my_files'';
  * any input/output files used by the task;
  * the configured database.

Also make sure that the Admidio account used with ''--as'' remains activated and an active member of the selected organization.

===== Integrating other applications =====

The CLI can be used as an administrative boundary between another application or migration script and Admidio.

Instead of writing directly to the Admidio database, an integration can invoke the relevant Admidio command.

For example, an external provisioning script can:

  - create a user with ''user:add'';
  - update profile fields with ''user:update'';
  - assign the user to a group with ''group:adduser'';
  - end a membership with ''group:deluser'';
  - inspect the resulting object through ''user:show --format=json''.

This approach has an important advantage over direct SQL: the command uses Admidio's normal entities, services, permissions, changelog and related update logic.

==== Example migration workflow ====

A typical migration from another membership system could proceed as follows:

  - create a database backup;
  - create or map the required Admidio groups;
  - inspect the configured profile fields with ''profile:fields'';
  - transform source data into the required internal field names;
  - call ''user:add'' or ''user:update'' for each person;
  - use ''group:adduser'' to recreate memberships and their start/end dates;
  - compare the resulting data using ''user:list'', ''group:members'' and JSON exports.

For large migrations, first test the complete process against a copy of the production installation.

===== Choosing identifiers in scripts =====

Many commands allow an object to be referenced by more than one identifier, for example:

  * UUID;
  * numeric database ID;
  * login name;
  * group or category name.

Interactive administration can conveniently use names:

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

For long-lived integrations, prefer UUIDs where the command accepts them.

Names may be changed and can sometimes be ambiguous. When a selector is ambiguous, the CLI fails rather than silently selecting one object.

===== Interactive and non-interactive commands =====

Commands that require confirmation ask interactively by default.

For example:

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

For a deliberately automated operation:

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

If a confirmation would be required and ''--no-interaction'' is present without ''--yes'', the command fails instead of silently continuing.

Do not add ''--yes'' indiscriminately to every automated command. It should show that the script intentionally accepts that operation.

===== Availability of registered commands =====

A command can be present in the registry but marked as unavailable when the corresponding web functionality does not yet have a reusable headless operation.

''admidio list'' shows this state, and ''admidio help COMMAND'' includes an availability notice.

Shell completion omits commands that are marked unavailable.

Do not work around an unavailable command by manipulating the Admidio database directly. Use the corresponding supported web functionality or wait until the required reusable core operation is available.

===== Troubleshooting =====

==== The CLI connects to the wrong database ====

The CLI loads ''adm_my_files/config.php'' from the Admidio installation.

If that configuration selects an environment based on ''HTTP_HOST'', specify the expected host:

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

or set:

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

==== The command says that --as is required ====

The selected command needs an acting Admidio identity.

Supply an activated user that is an active member of the current organization:

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

Remember that ''--as'' selects an identity; it does not perform password authentication.

==== The acting account is not activated or not an active member ====

An account used with ''--as'' must be activated and currently belong to the selected organization.

Activate/assign the account using normal Admidio administration before using it as an automation actor.

==== Permission denied / SYS_NO_RIGHTS ====

The CLI does not bypass Admidio permissions.

Check:

  * the selected organization;
  * the acting user;
  * whether the relevant component is visible/administrable to that user;
  * any object-specific or group/member rights required by the operation;
  * whether the command requires a full administrator.

==== A name is ambiguous ====

Use the UUID shown by the corresponding ''list'' or ''show'' command.

==== An output format is rejected ====

Not every format is valid for every command.

Use:

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

to see the exact allowed values.

==== A command is shown as unavailable ====

Read the availability explanation in:

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

The registry intentionally exposes the reason rather than silently offering an incomplete headless implementation.

==== A module's commands are missing ====

Module commands are loaded from:

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

If loading a module's CLI registration fails, the CLI writes a warning to standard error and continues loading the remaining commands. Inspect the warning and then run:

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

to see what was registered successfully.

===== Security recommendations =====

The CLI should be treated as an administrative server interface.

  * Restrict shell access to trusted users and service accounts.
  * Protect the Admidio source tree and ''adm_my_files'' with appropriate filesystem permissions.
  * Do not expose the CLI through a web-accessible wrapper.
  * Remember that ''--as'' is impersonation, not authentication.
  * Use a dedicated activated Admidio actor for automated tasks where appropriate.
  * Give that actor only the permissions required by the automation.
  * Use backups before bulk changes.
  * Prefer stdin-based secret input where a command supports it.
  * Avoid storing passwords, private keys or other secrets directly in shell scripts or shell history.
  * Protect generated backups and secret exports.
  * Prefer UUIDs in long-lived integration scripts.
  * Use JSON rather than parsing human-readable table output.
  * Check exit codes and do not ignore stderr.

===== Command reference =====

The complete command reference is generated directly from the installed CLI:

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

To generate a file suitable for the DokuWiki page:

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

See [[en:2.0:cli:commands|CLI command reference]].

Because that page is generated directly from the command registry, it should be considered the authoritative description of command arguments, options, aliases, declared rights and availability for a particular Admidio version.

The generated command reference is currently English-only because CLI help metadata is not yet localized.