Users¶

The user:* commands manage Omeka S user accounts and their API keys: create and update accounts, set passwords, enable or disable them, and hand out API keys to scripts and other applications.

A command that acts on an existing user takes its ID or email address (2 or jane.doe@example.org); the display name does not identify a user. user:exists is the exception: it only takes an email address.

Add a user¶

user:add takes the email address, the display name, the role and, optionally, the password:

omeka-s-cli user:add jane.doe@example.org "Jane Doe" editor "$JANE_PASSWORD"

The global roles of Omeka S are global_admin, site_admin, editor, reviewer, author and researcher; modules can add their own (the Guest module adds guest, for example). An unknown role is refused with the list of valid roles. Pass the password from an environment variable or a secret store, so it does not end up in your shell history.

Without a password the account exists but cannot log in, until you set one with user:update-password or the user resets it by email. --inactive creates a disabled account:

omeka-s-cli user:add john.roe@example.org "John Roe" researcher --inactive

Add users in a script that runs more than once¶

Adding an email address that already exists is an error. With --ignore-existing, user:add prints a warning and exits with 0 instead, so a provisioning script can be re-run:

omeka-s-cli user:add jane.doe@example.org "Jane Doe" editor "$JANE_PASSWORD" --ignore-existing

An existing account is left as it is: its name, role and password are not updated. To make a decision yourself, user:exists answers through its exit code: 0 when a user with that email address exists, 1 when it does not.

if ! omeka-s-cli user:exists cataloguer@example.org --quiet; then
    omeka-s-cli user:add cataloguer@example.org "Cataloguer" author "$CATALOGUER_PASSWORD"
fi

user:exists also prints a message on standard output; --quiet suppresses it.

List users¶

user:list shows every user with their ID, name, email address, status and role:

omeka-s-cli user:list

Found 4 user(s).
+----+--------------+------------------------+-----------+--------------+
| Id | Display Name | Email                  | Is Active | Role         |
+----+--------------+------------------------+-----------+--------------+
| 1  | Admin        | admin@example.org      | yes       | global_admin |
| 2  | Jane Doe     | jane.doe@example.org   | yes       | editor       |
| 3  | John Roe     | john.roe@example.org   | no        | researcher   |
| 4  | Cataloguer   | cataloguer@example.org | yes       | author       |
+----+--------------+------------------------+-----------+--------------+

--csv and --json give the same data in a form other tools can read. With --json, jq selects what a script needs, for example the email addresses of all global administrators:

omeka-s-cli user:list --json | jq -r '.[] | select(.role == "global_admin") | .email'

Change a user¶

user:update changes the display name (--name), email address (--email) or role (--role) of a user. Only the options you pass change; the rest of the account stays as it is:

omeka-s-cli user:update jane.doe@example.org --role site_admin --name "Jane A. Doe"

--activate and --deactivate do the same as user:enable and user:disable. Add --json to print the updated user.

Change a password¶

user:update-password sets a new password, for example to reset a forgotten one or to rotate the password of a service account:

omeka-s-cli user:update-password jane.doe@example.org "$NEW_PASSWORD"

Enable or disable a user¶

A disabled user keeps their account, content and site permissions, but cannot log in.

omeka-s-cli user:enable john.roe@example.org
omeka-s-cli user:disable cataloguer@example.org

Enabling an active user, or disabling a disabled one, only prints a warning. Like the other commands, both also accept the user ID; here the ID is looked up from the email address first:

id=$(omeka-s-cli user:list --json | jq -r '.[] | select(.email == "jane.doe@example.org") | .id')
omeka-s-cli user:disable "$id"

Delete a user¶

omeka-s-cli user:delete john.roe@example.org
omeka-s-cli user:delete cataloguer@example.org --ignore-not-found

Deleting a user that does not exist is an error; with --ignore-not-found the command prints a note and exits with 0. The resources the user created are kept, without an owner.

Manage API keys¶

Scripts and applications that use the Omeka S REST API authenticate with an API key, which belongs to a user and has that user's rights. user:create-api-key creates one under a label. The key consists of an identity (key_id) and a credential (key_credential). Omeka S stores only a hash of the credential, so it is shown once, at creation. In a script, capture it with --json:

key=$(omeka-s-cli user:create-api-key jane.doe@example.org importer --json)
KEY_IDENTITY=$(jq -r '.key_id' <<< "$key")
KEY_CREDENTIAL=$(jq -r '.key_credential' <<< "$key")

A client then passes both values on every API request, as the key_identity and key_credential query parameters. Store the credential in a secret store right away; if it is lost, delete the key and create a new one. The label must be unique per user.

user:list-api-keys shows the keys of a user, without their credentials:

omeka-s-cli user:list-api-keys jane.doe@example.org

Found 1 API key(s) for user 'jane.doe@example.org'.
+----------------------------------+-----------+---------+----------------------+
| Key Id                           | Key Label | User Id | User Email           |
+----------------------------------+-----------+---------+----------------------+
| KqjKj9rpinoqXyxOmFOEfOJrepiX6gvM | importer  | 2       | jane.doe@example.org |
+----------------------------------+-----------+---------+----------------------+

user:delete-api-key revokes a key by its label:

omeka-s-cli user:delete-api-key jane.doe@example.org importer

Reference¶

All commands also accept the global options.

user:add¶

Add a new user

omeka-s-cli user:add [options] <email> <name> <role> [password]

user:exists¶

Check if a user exists

omeka-s-cli user:exists <email>

user:list¶

List all users

omeka-s-cli user:list [options]

user:update¶

Update user details

omeka-s-cli user:update [options] <user>

user:update-password¶

Update the password of a user

omeka-s-cli user:update-password [options] <user> <password>

user:enable¶

Enable (activate) a user

omeka-s-cli user:enable [options] <user>

user:disable¶

Disable (deactivate) a user

omeka-s-cli user:disable [options] <user>

user:delete¶

Delete a user from Omeka S

omeka-s-cli user:delete [options] <user>

user:create-api-key¶

Create an API key for a user

omeka-s-cli user:create-api-key [options] <user> <label>

user:list-api-keys¶

List API keys for a user

omeka-s-cli user:list-api-keys [options] <user>

user:delete-api-key¶

Delete an API key for a user

omeka-s-cli user:delete-api-key [options] <user> <label>