Settings¶

The config:* commands read and change the settings Omeka S stores in its database: the global settings (the Settings page of the admin interface), the settings of each site, and the settings of each user. config:get, config:set and config:list work on single global settings; config:export and config:import move all three kinds to and from files, so you can keep them in version control or copy them to another instance. config:modules and config:themes list the installed modules and themes, to rebuild the same setup elsewhere.

The database connection itself (config/database.ini) is set up with config:create-db-ini, described on the Core page.

Read a setting¶

config:get prints the value of a global setting as JSON: a string comes in double quotes, a list as a JSON array.

omeka-s-cli config:get installation_title
omeka-s-cli config:get pagination_per_page

"Omeka S"
25

A setting that does not exist is an error (non-zero exit code). Pipe the output through jq -r . when you need the bare string; it also undoes the escaped slashes (Europe\/Brussels) in the JSON output.

config:list prints all global settings as one JSON object. With an argument, it only shows the settings whose name contains that text:

omeka-s-cli config:list per_page

{
    "pagination_per_page": 25
}

The names of all global settings:

omeka-s-cli config:list | jq -r 'keys[]'

Change a setting¶

config:set writes a global setting. The value is read as JSON when it is valid JSON, and as a plain string otherwise:

omeka-s-cli config:set installation_title "Digital Collections"   # a string
omeka-s-cli config:set pagination_per_page 50                      # a number
omeka-s-cli config:set version_notifications false                 # a boolean

So 50 is stored as a number and true/false as booleans. To store a string that would be valid JSON, such as a year or a number, pass it as a JSON string:

omeka-s-cli config:set installation_title '"2026"'

Lists and objects are JSON too. config:set replaces the whole value, so to add one item to a list, read it first:

extensions=$(omeka-s-cli config:get extension_whitelist | jq -c '. + ["heic"] | unique')
omeka-s-cli config:set extension_whitelist "$extensions"

Setting a value to null deletes the setting:

omeka-s-cli config:set docs_example_flag null

Export settings to files¶

config:export writes the settings to JSONC files (JSON that allows comments and trailing commas) in a directory, which it creates when needed:

omeka-s-cli config:export ~/settings-backup
ls ~/settings-backup

It writes one file per module and per kind of setting, named <module>.<type>.jsonc for global settings and <module>.<type>.<site or user>.jsonc for site and user settings, e.g. core.site_setting.collections.jsonc (site slug) or core.user_setting.admin-example-org.jsonc (user email). A setting belongs to a module when its name starts with the module id in lower case and an underscore (log_ for the Log module); everything else goes to core. Files with the same name are overwritten; other files in the directory are left alone.

Each file also records where it came from: the Omeka S version (for core) or the module version, the site slug or user email, and the export time. The import uses these to check the target instance.

Narrow the export down with --scope (setting, site_setting or user_setting), --module (a module id, or core), --site <id> or --user <id>:

omeka-s-cli config:export ~/settings-backup --scope setting --module core

When nothing matches, the command warns and writes no files.

Write a settings file¶

A settings file needs only type, module and settings; a site or user file also names its target by site (slug) or user (email). The two files below set three global settings and three settings of the site with the slug collections:

// Global settings of the Omeka S core
{
    "type": "setting",
    "module": "core",
    "settings": {
        "installation_title": "Digital Collections",
        "pagination_per_page": 50,
        "time_zone": "Europe/Brussels",
    }
}

// Settings of the site with the slug "collections"
{
    "type": "site_setting",
    "module": "core",
    "site": "collections",
    "settings": {
        "locale": "nl",
        "pagination_per_page": 12,
        "browse_attached_items": true
    }
}

Import settings¶

config:import reads a file, a URL, or a directory (all *.jsonc and *.json files in it, in name order). Preview first with --dry-run, which checks the files and the targets but writes nothing; add -v to see every key:

omeka-s-cli config:import ~/settings --dry-run

Dry run, no changes are made.
Previewing settings import; no changes will be written.
Would import 2 of 2 settings file(s).

Then import:

omeka-s-cli config:import ~/settings

The import only writes the keys in the files; other settings keep their value. Site and user files are matched by site slug and user email, not by the numeric id in the file, so an export from one instance imports into another. --scope and --module import only part of the files.

A file is skipped with a warning when its module is not active, or its site or user does not exist on this instance. A different Omeka S or module version than the one recorded in the file gives a warning too. With --strict, each of these is an error that stops the import.

All files are imported in one database transaction: when one fails, none of the changes are kept. Pass --no-transaction to write every setting immediately instead.

The core version setting is never imported, because Omeka S uses it to decide on database migrations; --force imports it anyway.

Remove settings that are not in the file¶

With --prune, the import also deletes the settings of the same module and kind (and the same site or user) that the file does not contain, so the instance ends up with exactly the settings in the file:

omeka-s-cli config:import ~/settings/core.site_setting.collections.jsonc --prune

List the installed modules and themes¶

config:modules lists the downloaded modules with their version and state; --installed keeps only the active and not_active (installed but disabled) ones:

omeka-s-cli config:modules --installed

+--------+---------+--------+
| Id     | Version | State  |
+--------+---------+--------+
| Common | 3.4.93  | active |
+--------+---------+--------+

To set up the same modules on another instance, save the list in the <id>:<version> form that module:download accepts:

omeka-s-cli config:modules --installed --json | jq -r '.[] | "\(.id):\(.version)"' > ~/modules.txt

and download and install each of them on the other instance (see Modules):

for module in $(cat ~/modules.txt); do
    omeka-s-cli module:download "$module" --install
done

A module that is already there is skipped with a warning, so the loop can run again.

config:themes does the same for themes; --active lists only the themes that a site uses:

omeka-s-cli config:themes --active --json

[
    {
        "id": "default",
        "version": "1.9.3",
        "active": true
    }
]

Both commands also have --env, which prints the list on one line (Common:3.4.93 Log:3.4.41) for reading; in scripts, use --json as above.

Reference¶

All commands also accept the global options.

config:get¶

Get global setting

omeka-s-cli config:get <id>

config:list¶

List all global settings

omeka-s-cli config:list [search]

config:set¶

Set global setting

omeka-s-cli config:set <id> <value>

config:export¶

Export instance settings to JSONC files

omeka-s-cli config:export [options] [output-dir]

config:import¶

Import instance settings from JSONC files

omeka-s-cli config:import [options] <source>

config:modules¶

Export list of modules

omeka-s-cli config:modules [options]

config:themes¶

Export list of themes

omeka-s-cli config:themes [options]