BookStack Code Mirror - website/blob - content/docs/admin/commands.md

   1 +++
   2 title = "Commands"
   3 description = "BookStack command-line actions"
   4 date = "2017-02-26"
   5 type = "admin-doc"
   6 +++
   7
   8 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 run `php artisan` from your BookStack install folder. Custom BookStack commands are all under the 'bookstack' namespace.
   9
  10 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.
  11
  12 {{<toc>}}
  13
  14 ### Create an Admin User
  15
  16 Create a new admin user via the command line. Can offer a good last resort if you ever get locked out the system.
  17 Will use the details provided as options otherwise will request them interactively.
  18
  19 ```bash
  20 # Interactive usage
  21 php artisan bookstack:create-admin
  22
  23 # Non-interactive usage example
  24 php artisan bookstack:create-admin --email="[email protected]" --name="Bazza" --password="hunter2"
  25
  26 # Defining "External Authentication ID" instead of password for LDAP/SAML2/OIDC environments
  27 php artisan bookstack:create-admin --email="[email protected]" --name="Bazza" --external-auth-id="bbooker"
  28 ```
  29
  30 ### Copy Shelf Permission
  31
  32 By default shelf permissions will not auto-cascade since a book can be in many shelves.
  33 This command will copy the permissions of a shelf to all child books.
  34 This can be done for a single shelf or for all shelves in the system:
  35
  36 ```bash
  37 # Run for all shelves
  38 php artisan bookstack:copy-shelf-permissions --all
  39
  40 # Run for a single shelf
  41 php artisan bookstack:copy-shelf-permissions --slug=my_shelf_slug
  42 ```
  43
  44 ### Update System URL
  45
  46 BookStack will store absolute URL paths for some content, such as images, in the database.
  47 If you change your base URL for BookStack this can be problematic.
  48 This command will essentially run a find & replace operation on all relevant tables in the database.
  49 Be sure to take a database backup for running this command.
  50
  51 ```bash
  52 # Searches for <oldUrl> and replaces it with <newUrl>
  53 php artisan bookstack:update-url <oldUrl> <newUrl>
  54
  55 # Example:
  56 php artisan bookstack:update-url http://docs.example.com https://demo.bookstackapp.com
  57 ```
  58
  59 ### Reset User MFA Methods
  60
  61 This will reset/clear any existing multi-factor-authentication methods for the given user. If MFA
  62 is enforced for one of their roles they'll be prompted to reconfigure MFA upon next login.
  63
  64 ```bash
  65 # Via email address:
  66 php artisan bookstack:reset-mfa [email protected]
  67
  68 # Via system ID:
  69 php artisan bookstack:reset-mfa --id=5
  70 ```
  71
  72 ### Refresh User Avatars
  73
  74 This will re-fetch avatar images for users in the system.
  75 By default avatars are fetched from [Gravatar](https://gravatar.com/) unless an alternative avatar system [has been configured](/docs/admin/other-config/#custom-user-avatar-fetching).
  76
  77 *Note: This will **not** load avatars from any connected authentication system.*
  78
  79 ```bash
  80 # Refresh avatar for just the user of the given email
  81 php artisan bookstack:refresh-avatar [email protected]
  82 # Or the user of the given id
  83 php artisan bookstack:refresh-avatar --id=101
  84
  85 # Refresh avatars for all users without avatars already assigned
  86 php artisan bookstack:refresh-avatar --users-without-avatars
  87
  88 # Refresh avatars for all users in the system
  89 php artisan bookstack:refresh-avatar --all
  90 ```
  91
  92 ### Delete All Activity History
  93
  94 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.
  95
  96 ```bash
  97 php artisan bookstack:clear-activity
  98 ```
  99
 100 ### Delete Page Revisions
 101
 102 By default this deletes all page revisions apart from page update drafts which share the same system.
 103 A `-a` flag can be used to also delete these update drafts.
 104
 105 ```bash
 106 # Delete just the page revisions
 107 php artisan bookstack:clear-revisions
 108
 109 # Delete all page revisions from the system including update drafts
 110 php artisan bookstack:clear-revisions -a
 111 ```
 112
 113 ### Delete Page Views
 114
 115 Delete tracked content views from the system. These are primarily used to populate any "Recently Used" lists.
 116
 117 ```bash
 118 php artisan bookstack:clear-views
 119 ```
 120
 121 ### Cleanup Unused Images
 122
 123 Searches and removes images that are not used in page content.
 124 While this can be done in the "Maintenance" section of the interface, running this via the command-line is often safer to avoid timeouts.
 125
 126 ```bash
 127 php artisan bookstack:cleanup-images
 128 ```
 129
 130 ### Regenerate the Search Index
 131
 132 BookStack uses a custom database-based search index system for efficient
 133 querying within the system. The command below re-builds this search index.
 134 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.
 135
 136 ```bash
 137 php artisan bookstack:regenerate-search
 138 ```
 139
 140 ### Regenerate Access Permissions
 141
 142 BookStack pre-calculates and stores certain access permissions in the database
 143 so that access can be calculated in a performant manner.
 144 The below command will regenerate these permissions.
 145 This is primarily used in development but can be useful if manually adding content via the database.
 146
 147 ```bash
 148 php artisan bookstack:regenerate-permissions
 149 ```
 150
 151 ### Regenerate Reference Index
 152
 153 BookStack stores references between content within the system to track how
 154 content is interlinked. Such references are generally managed by BookStack
 155 upon certain actions, such as when saving a page, but in some cases the
 156 below command may help to re-index these references.
 157 This can be useful upon upgrade of old content, or when manually adding content via the database.
 158
 159 ```bash
 160 php artisan bookstack:regenerate-references
 161 ```
 162
 163 ### Delete Users
 164
 165 Delete all users from the system that are not original "admin" or system-level users.
 166
 167 ```bash
 168 php artisan bookstack:delete-users
 169 ```
 170
 171 ### Generate UTF8mb4 SQL Upgrade Commands
 172
 173 Generates out the SQL which can be used to upgrade the database to UTF8mb4.
 174 See [UTF8mb4/Emoji Support](/docs/admin/ut8mb4-support/) for further details.
 175
 176 ```bash
 177 php artisan bookstack:db-utf8mb4
 178 ```