Modules¶

The module:* commands find modules in the online catalogs, download them into the modules/ directory of an Omeka S installation, and take them through their life cycle: install, enable, disable, update, upgrade, uninstall and delete. Commands that take a module id accept it in any case (sharing finds Sharing).

Find a module¶

module:search looks for the query in the id, name, description and tags of every module in the catalogs:

omeka-s-cli module:search sharing

+-------------+---------------+------------------------+
| Id          | LatestVersion | OmekaVersionConstraint |
+-------------+---------------+------------------------+
| ShareMeBaby | 1.2.4         | ^3.0.0 || ^4.0.0       |
| Sharing     | 1.5.0         | ^4.0.0                 |
+-------------+---------------+------------------------+

The Id column is what you pass to module:download. Add --extended for the URL, description, owner and the catalog a module comes from:

omeka-s-cli module:search mapping --extended

Without a query, module:search lists every module. The catalogs are downloaded on first use and cached for 24 hours in ~/.cache/omeka-s-cli; --refresh fetches them again.

Catalogs¶

Modules come from two catalogs, which module:repositories lists:

• omeka.org: the official add-ons directory, with the full release history of each module.
• daniel-km: the module list maintained by Daniel Berthereau, which also covers modules that are not registered on omeka.org, but only knows their latest release.

When a module is in both, the omeka.org entry wins. --repository limits a search to one catalog, and --unregistered shows only the modules that are missing from omeka.org:

omeka-s-cli module:repositories
omeka-s-cli module:search pdf --repository daniel-km
omeka-s-cli module:search --unregistered --json | jq length

Compatibility with your Omeka S version¶

Run inside an Omeka S installation, module:search hides the modules that have no release compatible with the installed Omeka S version. Outside an installation it lists everything. To see the hidden ones, add --include-incompatible:

omeka-s-cli module:search alttext
omeka-s-cli module:search alttext --include-incompatible

No modules found for query 'alttext'
+---------+---------------+------------------------+
| Id      | LatestVersion | OmekaVersionConstraint |
+---------+---------------+------------------------+
| AltText | 1.3.0         | ^3.1.0                 |
+---------+---------------+------------------------+

Download and install a module¶

module:download puts a module in the modules/ directory; module:install installs it in Omeka S, which also enables it:

omeka-s-cli module:download common
omeka-s-cli module:install Common

Without a version, module:download picks the most recent release whose Omeka S constraint matches the installed Omeka S version. If the latest release is too new for your installation, it warns and takes the newest one that fits.

Both steps are safe to re-run: a module that is already downloaded, or already installed, gives a warning and exit code 0. To download a module again, over the existing copy, add --force.

With --install, module:download installs the module right after downloading it:

omeka-s-cli module:download log --install

The Log module depends on Common: install the dependencies of a module first. The CLI does not resolve them for you: installing a module whose dependency is missing fails with an error. Note that --install is skipped when the module was already downloaded.

Pin a version¶

Add the version after a colon to download a specific release:

omeka-s-cli module:download sharing:1.4.0 --install

Pinning works for modules in the omeka.org catalog. The daniel-km catalog only knows the latest release, so for a module that is only listed there, download an older version from its release zip or git repository instead (see below).

A pinned version must be compatible with the installed Omeka S version, or the download fails. On Omeka S 4.2, module:download csseditor:1.3.0 (a release for Omeka S 3) gives:

Cannot use module 'CSSEditor' version '1.3.0': incompatible with Omeka S 4.2.1.

--force skips this check. It also lets you download a release that has no Omeka S constraint in the catalog: the automatic selection treats such releases as incompatible, so pin their version.

Download from a zip file or a git repository¶

The argument of module:download is a module URI. Besides a catalog id, it accepts a release zip, on the web or on disk, and a git repository:

A release zip from the web:

omeka-s-cli module:download https://github.com/omeka-s-modules/CSSEditor/releases/download/v1.3.1/CSSEditor-1.3.1.zip

A zip file on disk (a relative path is relative to the current directory):

curl -sSL -o /tmp/CSSEditor-1.3.1.zip \
    https://github.com/omeka-s-modules/CSSEditor/releases/download/v1.3.1/CSSEditor-1.3.1.zip
omeka-s-cli module:download /tmp/CSSEditor-1.3.1.zip --force

A git repository, at a tag, branch or commit given after # (the default branch without it). gh: is short for a repository on GitHub:

omeka-s-cli module:download https://github.com/omeka-s-modules/CSSEditor.git#v1.3.1 --force
omeka-s-cli module:download gh:omeka-s-modules/CSSEditor#v1.3.1 --force

git must be installed for these. The clone keeps its .git directory. With a zip or git source, the module directory is named after the namespace in the module's Module.php, and the version is not checked against your Omeka S version.

If the downloaded module has a composer.lock but no vendor/ directory, as is common for a git checkout, module:download runs composer install --no-dev in it. That needs composer on the PATH.

Keep the previous copy¶

When --force replaces a module, the old directory is deleted. Add --backup to move it to ~/.omeka-s-cli/backups/modules/<module>/<date-time>/ instead:

omeka-s-cli module:download gh:omeka-s-modules/CSSEditor#v1.3.1 --force --backup

List modules and check their status¶

module:list shows every module in the modules/ directory, with its state, the version on disk, the version recorded in the database, and the latest version in the catalogs:

omeka-s-cli module:list

+---------+---------+--------+---------+------------------+---------------+-----------------+-------------------+
| Id      | Name    | State  | Version | InstalledVersion | LatestVersion | UpdateAvailable | Author            |
+---------+---------+--------+---------+------------------+---------------+-----------------+-------------------+
| Common  | Common  | active | 3.4.93  | 3.4.93           | 3.4.93        | no              | Daniel Berthereau |
| Log     | Log     | active | 3.4.41  | 3.4.41           | 3.4.41        | no              | Daniel Berthereau |
| Sharing | Sharing | active | 1.4.0   | 1.4.0            | 1.5.0         | yes             | Omeka Team        |
+---------+---------+--------+---------+------------------+---------------+-----------------+-------------------+

The state is the one Omeka S reports: active, not_active (installed, but disabled), not_installed, needs_upgrade (the files are newer than the installed version), or an error state such as invalid_omeka_version or invalid_ini. --extended adds the path of each module.

--active, --not-active, --not-installed and --needs-upgrade filter on the state (combine them to show several), --outdated on the update column. For anything else, filter the --json output with jq:

omeka-s-cli module:list --not-active
omeka-s-cli module:list --json | jq -r '.[] | select(.state != "active") | .id'

module:status shows the same row for one module, and fails if the module is not in modules/:

omeka-s-cli module:status Sharing
omeka-s-cli module:status Sharing --json | jq -r '.[0].state'

Enable and disable modules¶

A disabled module stays installed, with its data, but Omeka S does not load it:

omeka-s-cli module:disable Sharing
omeka-s-cli module:enable Sharing

Enabling an active module, or disabling a disabled one, gives a warning and exit code 0.

Act on all modules at once¶

module:install, module:enable, module:disable and module:upgrade accept --all instead of a module id. They act on every module in the matching state, in dependency order: dependencies are installed, enabled and upgraded before the modules that need them, and disabled after them. The commands that change modules, except module:download, also take --dry-run, which reports what they would do without doing it:

omeka-s-cli module:disable --all --dry-run

Dry run, no changes are made.
3 module(s) would be disabled: Sharing, Log, Common.

A module that fails does not stop the others.

Update modules¶

module:list --outdated shows the modules for which the catalogs have a newer release:

omeka-s-cli module:list --outdated

+---------+---------+--------+---------+------------------+---------------+-----------------+------------+
| Id      | Name    | State  | Version | InstalledVersion | LatestVersion | UpdateAvailable | Author     |
+---------+---------+--------+---------+------------------+---------------+-----------------+------------+
| Sharing | Sharing | active | 1.4.0   | 1.4.0            | 1.5.0         | yes             | Omeka Team |
+---------+---------+--------+---------+------------------+---------------+-----------------+------------+

module:update downloads the newest compatible release over the installed copy (it runs module:download --force). With --upgrade it then runs the module's database upgrade, like the Upgrade button in the admin interface:

omeka-s-cli module:update Sharing --upgrade

You can also pass a version (module:update sharing:1.5.0). --all updates every module that --outdated lists; check the list with --dry-run first:

omeka-s-cli module:update --all --upgrade --dry-run

Upgrade¶

Without --upgrade, an updated module is left in the needs_upgrade state, and Omeka S does not load it until it is upgraded. module:upgrade runs the pending upgrades; this is also the step to take after replacing module files yourself, or after a core update:

omeka-s-cli module:update Sharing
omeka-s-cli module:list --needs-upgrade
omeka-s-cli module:upgrade --all

Uninstall and delete modules¶

module:uninstall runs the module's uninstaller, which usually removes its tables and settings: the module's data is lost. module:delete then removes its directory:

omeka-s-cli module:uninstall Sharing
omeka-s-cli module:delete Sharing

module:delete refuses an installed module. With --force it uninstalls the module first, then deletes it:

omeka-s-cli module:delete Log --force

To clean up in bulk, module:uninstall --not-active uninstalls every disabled module (--all every installed one), and module:delete --not-installed removes every module that is not installed. A module in the needs_upgrade state cannot be uninstalled: module:uninstall --all skips it with a warning.

omeka-s-cli module:uninstall --not-active --dry-run
omeka-s-cli module:delete --not-installed --dry-run

Missing modules¶

module:uninstall, module:disable and module:delete fail when the module does not exist. With --ignore-not-found they print a note and exit 0, so a cleanup step can run more than once:

omeka-s-cli module:delete Sharing --force --ignore-not-found

Reference¶

All commands also accept the global options.

module:search¶

Search/list available modules

omeka-s-cli module:search [options] [query]

module:repositories¶

List available module repositories

omeka-s-cli module:repositories [options]

module:download¶

Download module

omeka-s-cli module:download [options] <module>

module:install¶

Install module

omeka-s-cli module:install [options] [module-id]

module:list¶

List downloaded modules

omeka-s-cli module:list [options]

module:status¶

Get module status

omeka-s-cli module:status [options] <module-id>

module:enable¶

Enable module

omeka-s-cli module:enable [options] [module-id]

module:disable¶

Disable module

omeka-s-cli module:disable [options] [module-id]

module:update¶

Update module

omeka-s-cli module:update [options] [module-id]

module:upgrade¶

Upgrade module

omeka-s-cli module:upgrade [options] [module-id]

module:uninstall¶

Uninstall module

omeka-s-cli module:uninstall [options] [module-id]

module:delete¶

Delete module

omeka-s-cli module:delete [options] [module-id]