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

   1 +++
   2 title = "BookStack System CLI"
   3 date = "2023-06-32"
   4 type = "admin-doc"
   5 +++
   6
   7 The BookStack System CLI allows easy running of BookStack infrastructure-level tasks
   8 such as backing up, restoring or updating. The CLI is distributed with
   9 the BookStack project source code, although the CLI is self-contained and can run independently
  10 of a BookStack instance.
  11
  12 ***Warning:** The System CLI was added in BookStack v23.05 in an alpha state and currently
  13 remains in that non-production state until it has been well tested.
  14 Please use the CLI with caution, and ensure you fully & periodically test any processes where the CLI is relied upon.*
  15
  16 {{<toc>}}
  17
  18 ---
  19
  20 ### CLI Usage
  21
  22 The CLI is included with the BookStack codebase, so you can usually run it like so:
  23
  24 ```bash
  25 # Go to your BookStack install
  26 cd /var/www/bookstack
  27
  28 # Run the CLI
  29 ./bookstack-system-cli
  30 ```
  31
  32 The CLI is built using PHP.
  33 Depending on operating system and permissions, you may need to instead run it directly via PHP like so:
  34
  35 ```bash
  36 php ./bookstack-system-cli
  37 ```
  38
  39 By default, without any arguments provided, the CLI will list the available commands which are documented [in more detail below](#available-commands).
  40 With any command, you can pass a `-h` option to show additional per-command details and options.
  41
  42 ---
  43
  44 ### Standalone Usage
  45
  46 It's possible to use the CLI without it being part of a BookStack instance. This can be useful if using it to create
  47 a new BookStack install instance.
  48
  49 You can grab a copy of the CLI from the `release` branch of the [core project GitHub repo](https://github.com/BookStackApp/BookStack/blob/release/bookstack-system-cli).
  50 Below is how you might fetch the CLI, and make it globally available on the command line, on a Linux server:
  51
  52 ```bash
  53 # Download the raw CLI file from GitHub
  54 curl https://github.com/BookStackApp/BookStack/raw/release/bookstack-system-cli -sLo bookstack-system-cli
  55
  56 # Made the CLI executable by default
  57 chmod +x bookstack-system-cli
  58
  59 # Move into a globally accessible PATH location
  60 sudo mv bookstack-system-cli /usr/local/bin/bookstack-system-cli
  61
  62 # Run the CLI
  63 bookstack-system-cli
  64 ```
  65
  66 ---
  67
  68 ### Available Commands
  69
  70 #### backup
  71
  72 Backup a BookStack installation to a single compressed ZIP file.
  73 By default this will attempt to backup anything that may be expected to be user-generated, or admin edited, within an install.
  74 This includes a database dump of everything within the connected BookStack database instance, along with the current `.env` file in use.
  75 The backup will also attempt to include a copy of the CLI itself in the backup, so the exact same CLI can be used for restore where required.
  76
  77 Note that this won't attempt backup of anything on remote systems, like those uploaded when BookStack is configured to use S3 file storage.
  78
  79 If a backup target output ZIP is not provided as a first additional argument, it will be saved to the `storage/backups` folder, relative to
  80 the BookStack root installation folder, with a name in the format:
  81
  82 ```
  83 bookstack-backup-<year>-<month>-<day>-<time>.zip
  84 ```
  85
  86 When successful, the CLI will report the backup ZIP location upon completion.
  87
  88 ##### Usage Examples
  89
  90 ```bash
  91 # Create a backup in the default "storage/backups" directory of a BookStack install
  92 ./bookstack-system-cli backup
  93
  94 # Create a backup, specifying the target output file name and location
  95 # as the first additional argument
  96 ./bookstack-system-cli backup ~/my-backup.zip
  97 ```
  98
  99 ##### Command Options
 100
 101 - `--no-database` Skip inclusion of a database dump, containing your main BookStack content.
 102 - `--no-uploads` Skip backup of any local file or image uploads.
 103 - `--no-themes` Skip backup of any custom theme files.
 104 - `--app-directory=<path>` Provide a path to the BookStack instance to back up. When not provided, the CLI will attempt to locate the BookStack install based upon current working directory and the location of the CLI itself.
 105
 106 #### restore
 107
 108 Restore the provided ZIP file into an existing BookStack installation.
 109 The ZIP file should be one created via the `backup` command, or at least in a compatible format.
 110
 111 When ran, the command will attempt to resolve any APP_URL, or database, `.env` changes that might need to be made
 112 when the backed-up `.env` file is restored.
 113
 114 ##### Usage Examples
 115
 116 ```bash
 117 # Restore the ~/my-backup.zip backup file into the current BookStack instance
 118 ./bookstack-system-cli restore ~/my-backup.zip
 119 ```
 120
 121 ##### Command Options
 122
 123 - `--app-directory=<path>` Provide a path to the BookStack instance to back up. When not provided, the CLI will attempt to locate the BookStack install based upon current working directory and the location of the CLI itself.
 124
 125 #### update
 126
 127 Update the existing BookStack installation to the latest version.
 128 This runs an instance through the standard BookStack [update commands](/docs/admin/updates) to bring it up to the latest release version.
 129
 130 ##### Usage Examples
 131
 132 ```bash
 133 # Update the current BookStack instance
 134 ./bookstack-system-cli update
 135 ```
 136
 137 ##### Command Options
 138
 139 - `--app-directory=<path>` Provide a path to the BookStack instance to back up. When not provided, the CLI will attempt to locate the BookStack install based upon current working directory and the location of the CLI itself.
 140
 141 #### init
 142
 143 Initialize a new BookStack installation in the given folder.
 144 This clones down the BookStack project, installs PHP dependencies, creates a fresh `.env` file for editing, then generates a key for the `.env` file.
 145
 146 Note that this won't do everything for a new BookStack install, you'll still need to configure your database details then migrate the database, and configure your system's web-server (and any required permissions).
 147
 148 ##### Usage Examples
 149
 150 ```bash
 151 # Initialize a new BookStack install in the current folder
 152 ./bookstack-system-cli init
 153
 154 # Initialize a new BookStack install at the "/var/www/new-bookstack" path
 155 ./bookstack-system-cli init /var/www/new-bookstack
 156 ```
 157
 158 ---
 159
 160 ### CLI Source Code & Project
 161
 162 The CLI is maintained as its own project within the [BookStackApp/system-cli Codeberg project](https://codeberg.org/bookstack/system-cli).
 163 There you can find the source code, development details and known issues.