Skip to content

B2SHARE CLI Commands#

The B2SHARE command-line interface (b2share CLI) is a set of commands used to create and manage B2share instance. The B2SHARE CLI is an useful tool that allowes admins to set up and manage communities, records, indexes, etc..

The document will show examples of usefull CLI commands available in the b2share CLI. For additional information check the Invenio v3 documentation.

How to run B2SHARE CLI#

B2SHARE CLI commands can be run inside the b2share running container. 

docker-compose exec -i  b2share bash # if you are using docker-compose v1 
or 
docker compose exec -i  b2share bash # if you are using docker-compose v2
alternatively 
docker exec -it <b2share-container-id> bash

Availables CLI commands#

To run the b2share cli, execute in the docker container the following command: 

b2share [COMMAND] [OPTIONS] [ARGUMENTS]
The following commands are available at the moment:

  • access : Account commands.
  • alembic : Perform database migrations.
  • assets : Web assets commands.
  • collect : Collect static files.
  • communities : communities management commands.
  • db : Database commands.
  • demo : Demonstration commands.
  • deposit : Deposit management commands.
  • files : Files management commands.
  • index : Manage search indices.
  • instance : Instance commands.
  • linkset : linkset commands.
  • migrate : Migration commands.
  • npm : Generate a package.json file.
  • oai : OAI commands.
  • ownership : ownership management commands.
  • pid : PID-Store management commands.
  • queues : Manage events queue.
  • records : Record management commands.
  • roles : Role commands.
  • run : Runs a development server.
  • schemas : Schemas management commands.
  • shell : Runs a shell in the app context.
  • upgrade : B2SHARE upgrade commands.
  • users : User commands.

b2share access#

All operations below will try to identify the user based on the email address. The user must have logged in into B2SHARE at least once, otherwise the email address will not be found in the database.

Commands: 

  allow   Allow actions.
  deny    Deny actions.
  list    List all registered actions.
  remove  Remove existing action authorization.
  show    Show all assigned actions.

Assign superuser-access to a user#

b2share access allow -e ${USER_EMAIL} superuser-access

Revoke superadministrator rights#

b2share access remove -e ${USER_EMAIL} superuser-access

List existing rights#

b2share access show -e ${USER_EMAIL}

b2share communities#

Communities management commands.

Commands: 

  create      Create a community in the database.
  edit        Edit data of the specified community.
  list        List all communities in this instances' database
  policies    Manage community policies
  roles       Manage community roles
  set_schema  Set the community block schema and/or root schema version. If a root
              schema version is given, but no JSON file, the latest known block schema
              will be used (if present).

Usage examples:

List communities#

b2share communities list

Create a community#

To create a community, make sure that B2SHARE_UI_PATH is defined in your environment. The ${COMMUNITY_LOGO} parameter must be the filename of an image file, already located in the $B2SHARE_UI_PATH/img/communities/directory.

If the file is not present in the running container, you can copy in the correct location usign the following command: 

docker cp <IMAGE_NAME> <CONTAINER_ID>:$B2SHARE_UI_PATH/img/communities/${COMMUNITY_LOGO}
where <CONTAINER_ID> is the ID of the running b2share container.

b2share communities create ${COMMUNITY} ${COMMUNITY_NAME} ${COMMUNITY_LOGO}

Edit communities#

To edit a community, use the b2share communities edit command, with the necessary arguments. For more information run: 

b2share communities edit [OPTIONS] <COMMUNITY_ID>
Where the options are: 
  -v, --verbose
  --name TEXT
  --description TEXT
  --logo TEXT
  --clear_fields      if set edit nullifies unspecified value options
Note

After a community name or description is updated, please make sure to also run the following command, which synchronizes the list of communities with the OAI-PMH declared sets: 

b2share oai update_sets

Set community schema#

To update a root schema for a B2SHARE community, it is important to run all these commands in b2share container: 

b2share communities set_schema "${COMMUNITY}" --no-block
b2share communities set_schema "${COMMUNITY}" --root-schema  <root schema version>  
b2share communities set_schema "${COMMUNITY}" ${COMMUNITY_SPECIFIC_METADATA_JSON_SCHEMA}

Note:

THERE IS A BUG IN b2share communities set_schema WHICH DELETES THE COMMUNITY SPECIFIC PART OF THE SCHEMA UNLESS YOU PROVIDE ONE EXPLICITLY.

b2share index#

Manage search indices.

Commands: 

  create   Create new index.
  delete   Delete index by its name.
  destroy  Destroy all indexes.
  init     Initialize registered aliases and mappings.
  put      Index input data.
  queue    Manage indexing queue.
  reindex  Reindex all records.
  run      Run bulk record indexing.

Detroy and recreate indexes after a database migration#

b2share index destroy --force --yes-i-know
b2share index init --force
b2share index queue init purge

b2share index reindex --yes-i-know
b2share index run

b2share roles#

Commands to manage roles.

Commands: 

  add     Add user to role.
  create  Create a role.
  list    List all known roles (for a user)
  remove  Remove user from role.

Add role to existing user#

Before running the command check if an user exixts. You can do that with the b2share-user cli. 

b2share roles add ${USER_EMAIL} ${ROLE_NAME}

b2share schemas#

Schemas management commands.

Commands: 

  block_schema_add                Adds a block schema to the database.
  block_schema_create_version     Assign a json-schema file conforming to
                                  the...
  block_schema_edit
  block_schema_list               Lists all block schemas for this b2share...
  block_schema_list_versions      show the version number and release date
                                  of...
  block_schema_version_generate_json
                                  print json_schema of a particular block...
  community_schema_list           Lists all community schema versions for
                                  this...
  community_schema_list_block_schema_versions
                                  Show the block schema versions in the...
  init                            CLI command loading Root Schema files in
                                  the...

How to fetch an existing schema#

  1. Get the BLOCK SCHEMA ID from an existing schema running: bash b2share schemas block_schema list
  2. Generate the schema as json file running: 
    b2share schemas block_schema_version_generate_json BLOCK_SCHEMA_ID

b2share users#

User management commands. Commands: 

  activate    Activate a user.
  anonymize   delete a user given a user_id or a user_email. If you use both of them
              only the user_id will be used. Anonymize will not delete completely 
              the user but will replace the real user with an anonymous fake one.
  create      Create a user.
  deactivate  Deactivate a user.
  delete      delete a user given a user_id or a user_email. If you use both of them
              only the user_id will be used.
  find        Get user info from user_id or user_email.
  list        List all known users

Create User#

b2share users create --password ${PASSWORD} --active ${USER_EMAIL}

Remember to use the --active flag to activate the user immidiately after the creation.

List Users (b2share-v2.2.0)#

The following command will print for you USER_ID, ACTIVE_FLAG, EMAIL, ROLES for each user in the db. 

b2share users list

Find User (b2share-v2.2.3)#

b2share users find --user_id ${USER_ID}
or
b2share users find --user_email ${USER_EMAIL}

  Last update: 30.11.2023