Commands

BookStack has some command line actions that can help with maintenance and common operations. There are also many commands available from the underlying Laravel framework. To list all available commands you can simply runphp artisan from your BookStack install folder. Custom BookStack commands are all under the ‘bookstack’ namespace.

Below is a listing of the BookStack specific commands. For any you can provide a-h option to list details and options for the command.

Create an Admin User

Create a new admin user via the command line. This can offer a good last resort if you ever get locked out the system, and can beuseful in setting the default admin user credentials for a new instance.Will use the details provided as options otherwise will request them interactively.

 1 2 3 4 5 6 7 8 91011121314151617

# Interactive usagephp artisan bookstack:create-admin# Non-interactive usage examplephp artisan bookstack:create-admin --email="barry@example.com" --name="Bazza" --password="hunter2"# Defining "External Authentication ID" instead of password for LDAP/SAML2/OIDC environmentsphp artisan bookstack:create-admin --email="barry.booker@example.com" --name="Bazza" --external-auth-id="bbooker"# Generate a random password for the created user# The password will be provided back via STDOUT as the only output on success for automation usephp artisan bookstack:create-admin --email="jerry@example.com" --name="Jez" --generate-password# Updates the default "admin@admin.com" user if it exists, otherwise creates a new admin# user if none already exists, otherwise skips user creation with an exit code of 2.# This would be typically used in non-interactive scripted scenarios to set the initial admin user.php artisan bookstack:create-admin --initial --email="danny@example.com" --name="Danny Admin" --generate-password

Copy Shelf Permission

By default shelf permissions will not auto-cascade since a book can be in many shelves.This command will copy the permissions of a shelf to all child books.This can be done for a single shelf or for all shelves in the system:

12345

# Run for all shelvesphp artisan bookstack:copy-shelf-permissions --all# Run for a single shelfphp artisan bookstack:copy-shelf-permissions --slug=my_shelf_slug

Update System URL

BookStack will store absolute URL paths for some content, such as images, in the database.If you change your base URL for BookStack this can be problematic.This command will essentially run a find & replace operation on all relevant tables in the database.Be sure to take a database backup for running this command.

12345

# Searches for <oldUrl> and replaces it with <newUrl>php artisan bookstack:update-url <oldUrl> <newUrl># Example:php artisan bookstack:update-url http://docs.example.com https://demo.bookstackapp.com

Thiswill not change theAPP_URL option set in your configuration. If changing your BookStack URL, you will also need to change that.env file option to match your new instance URL.

Reset User MFA Methods

This will reset/clear any existing multi-factor-authentication methods for the given user. If MFAis enforced for one of their roles they’ll be prompted to reconfigure MFA upon next login.

12345

# Via email address:php artisan bookstack:reset-mfa --email=john@example.com# Via system ID:php artisan bookstack:reset-mfa --id=5

Refresh User Avatars

This will re-fetch avatar images for users in the system.By default avatars are fetched fromGravatar unless an alternative avatar systemhas been configured.

Note: This willnot load avatars from any connected authentication system.

 1 2 3 4 5 6 7 8 910

# Refresh avatar for just the user of the given emailphp artisan bookstack:refresh-avatar --email=user@example.com# Or the user of the given idphp artisan bookstack:refresh-avatar --id=101# Refresh avatars for all users without avatars already assignedphp artisan bookstack:refresh-avatar --users-without-avatars# Refresh avatars for all users in the systemphp artisan bookstack:refresh-avatar --all

Delete All Activity History

This will clear all tracked activities in the system. Note: Some areas of the interface rely on this data, including the Audit Log and any “Recent Activity” lists.

1

php artisan bookstack:clear-activity

Delete Page Revisions

By default this deletes all page revisions apart from page update drafts which share the same system.A-a flag can be used to also delete these update drafts.

12345

# Delete just the page revisionsphp artisan bookstack:clear-revisions# Delete all page revisions from the system including update draftsphp artisan bookstack:clear-revisions -a

Delete Page Views

Delete tracked content views from the system. These are primarily used to populate any “Recently Used” lists.

1

php artisan bookstack:clear-views

Cleanup Unused Images

Searches and removes images that are not used in page content.While this can be done in the “Maintenance” section of the interface, running this via the command-line is often safer to avoid timeouts.

1

php artisan bookstack:cleanup-images

Regenerate the Search Index

BookStack uses a custom database-based search index system for efficientquerying within the system. The command below re-builds this search index.This does not usually need to be manually ran, but it can be useful if manually inserting pages into the system or to pick-up BookStack indexing changes.

1

php artisan bookstack:regenerate-search

Regenerate Access Permissions

BookStack pre-calculates and stores certain access permissions in the databaseso that access can be calculated in a performant manner.The below command will regenerate these permissions.This is primarily used in development but can be useful if manually adding content via the database.

1

php artisan bookstack:regenerate-permissions

Regenerate Reference Index

BookStack stores references between content within the system to track howcontent is interlinked. Such references are generally managed by BookStackupon certain actions, such as when saving a page, but in some cases thebelow command may help to re-index these references.This can be useful upon upgrade of old content, or when manually adding content via the database.

1

php artisan bookstack:regenerate-references

Assign Sort Rule

Assigns and runs the specifiedsort rule to the specified content in batch.Running the command without any arguments will list the existing sort rulesin the system as an easy method to get their IDs.A flag is required to specify which content to assign the rule to. The available optionsare shown in the examples below.

 1 2 3 4 5 6 7 8 9101112131415

# Formatphp artisan bookstack:assign-sort-rule <sort_rule_id> <assignment-flag># Assign sort rule 4 to all booksphp artisan bookstack:assign-sort-rule4 --all-books# Assign sort rule 19 to all books which don't already have a sort rule assignedphp artisan bookstack:assign-sort-rule19 --books-without-sort# Assign sort rule 2 to books which already have sort rule 7 assigned# This is useful to switch the sort rule of many booksphp artisan bookstack:assign-sort-rule2 --books-with-sort=7# List out available sort rulesphp artisan bookstack:assign-sort-rule

Delete Users

Delete all users from the system that are not original “admin” or system-level users.

1

php artisan bookstack:delete-users

Generate UTF8mb4 SQL Upgrade Commands

Generates out the SQL which can be used to upgrade the database to UTF8mb4.SeeUTF8mb4/Emoji Support for further details.

1

php artisan bookstack:db-utf8mb4