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 This **will not** change the `APP_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.
  60
  61 ### Reset User MFA Methods
  62
  63 This will reset/clear any existing multi-factor-authentication methods for the given user. If MFA
  64 is enforced for one of their roles they'll be prompted to reconfigure MFA upon next login.
  65
  66 ```bash
  67 # Via email address:
  68 php artisan bookstack:reset-mfa [email protected]
  69
  70 # Via system ID:
  71 php artisan bookstack:reset-mfa --id=5
  72 ```
  73
  74 ### Refresh User Avatars
  75
  76 This will re-fetch avatar images for users in the system.
  77 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).
  78
  79 *Note: This will **not** load avatars from any connected authentication system.*
  80
  81 ```bash
  82 # Refresh avatar for just the user of the given email
  83 php artisan bookstack:refresh-avatar [email protected]
  84 # Or the user of the given id
  85 php artisan bookstack:refresh-avatar --id=101
  86
  87 # Refresh avatars for all users without avatars already assigned
  88 php artisan bookstack:refresh-avatar --users-without-avatars
  89
  90 # Refresh avatars for all users in the system
  91 php artisan bookstack:refresh-avatar --all
  92 ```
  93
  94 ### Delete All Activity History
  95
  96 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.
  97
  98 ```bash
  99 php artisan bookstack:clear-activity
 100 ```
 101
 102 ### Delete Page Revisions
 103
 104 By default this deletes all page revisions apart from page update drafts which share the same system.
 105 A `-a` flag can be used to also delete these update drafts.
 106
 107 ```bash
 108 # Delete just the page revisions
 109 php artisan bookstack:clear-revisions
 110
 111 # Delete all page revisions from the system including update drafts
 112 php artisan bookstack:clear-revisions -a
 113 ```
 114
 115 ### Delete Page Views
 116
 117 Delete tracked content views from the system. These are primarily used to populate any "Recently Used" lists.
 118
 119 ```bash
 120 php artisan bookstack:clear-views
 121 ```
 122
 123 ### Cleanup Unused Images
 124
 125 Searches and removes images that are not used in page content.
 126 While this can be done in the "Maintenance" section of the interface, running this via the command-line is often safer to avoid timeouts.
 127
 128 ```bash
 129 php artisan bookstack:cleanup-images
 130 ```
 131
 132 ### Regenerate the Search Index
 133
 134 BookStack uses a custom database-based search index system for efficient
 135 querying within the system. The command below re-builds this search index.
 136 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.
 137
 138 ```bash
 139 php artisan bookstack:regenerate-search
 140 ```
 141
 142 ### Regenerate Access Permissions
 143
 144 BookStack pre-calculates and stores certain access permissions in the database
 145 so that access can be calculated in a performant manner.
 146 The below command will regenerate these permissions.
 147 This is primarily used in development but can be useful if manually adding content via the database.
 148
 149 ```bash
 150 php artisan bookstack:regenerate-permissions
 151 ```
 152
 153 ### Regenerate Reference Index
 154
 155 BookStack stores references between content within the system to track how
 156 content is interlinked. Such references are generally managed by BookStack
 157 upon certain actions, such as when saving a page, but in some cases the
 158 below command may help to re-index these references.
 159 This can be useful upon upgrade of old content, or when manually adding content via the database.
 160
 161 ```bash
 162 php artisan bookstack:regenerate-references
 163 ```
 164
 165 ### Assign Sort Rule
 166
 167 Assigns and runs the specified [sort rule](/docs/user/organising-content/#sort-rules) to the specified content in batch.
 168 Running the command without any arguments will list the existing sort rules
 169 in the system as an easy method to get their IDs.
 170 A flag is required to specific which content to assign the rule to. The available options
 171 are shown in the examples below.
 172
 173 ```bash
 174 # Format
 175 php artisan bookstack:assign-sort-rule <sort_rule_id> <assignment-flag>
 176
 177 # Assign sort rule 4 to all books
 178 php artisan bookstack:assign-sort-rule 4 --all-books
 179
 180 # Assign sort rule 19 to all books which don't already have a sort rule assigned
 181 php artisan bookstack:assign-sort-rule 19 --books-without-sort
 182
 183 # Assign sort rule 2 to books which already have sort rule 7 assigned
 184 # This is useful to switch the sort rule of many books
 185 php artisan bookstack:assign-sort-rule 2 --books-with-sort=7
 186
 187 # List out available sort rules
 188 php artisan bookstack:assign-sort-rule
 189 ```
 190
 191 ### Delete Users
 192
 193 Delete all users from the system that are not original "admin" or system-level users.
 194
 195 ```bash
 196 php artisan bookstack:delete-users
 197 ```
 198
 199 ### Generate UTF8mb4 SQL Upgrade Commands
 200
 201 Generates out the SQL which can be used to upgrade the database to UTF8mb4.
 202 See [UTF8mb4/Emoji Support](/docs/admin/ut8mb4-support/) for further details.
 203
 204 ```bash
 205 php artisan bookstack:db-utf8mb4
 206 ```