From: Dan Brown Date: Fri, 23 Jun 2023 17:46:20 +0000 (+0100) Subject: Added system CLI admin doc page X-Git-Url: http://source.bookstackapp.com/website/commitdiff_plain/d128335a9b6c38fa37a05478fa4e1929de7f4588 Added system CLI admin doc page --- diff --git a/content/docs/admin/system-cli.md b/content/docs/admin/system-cli.md new file mode 100644 index 0000000..1783d8a --- /dev/null +++ b/content/docs/admin/system-cli.md @@ -0,0 +1,163 @@ ++++ +title = "BookStack System CLI" +date = "2023-06-32" +type = "admin-doc" ++++ + +The BookStack System CLI allows easy running of BookStack infrastructure-level tasks +such as backing up, restoring or updating. The CLI is distributed with +the BookStack project source code, although the CLI is self-contained and can run independently +of a BookStack instance. + +***Warning:** The System CLI was added in BookStack v23.05 in an alpha state and currently +remains in that non-production state until it has been well tested. +Please use the CLI with caution, and ensure you fully & periodically test any processes where the CLI is relied upon.* + +{{}} + +--- + +### CLI Usage + +The CLI is included with the BookStack codebase, so you can usually run it like so: + +```bash +# Go to your BookStack install +cd /var/www/bookstack + +# Run the CLI +./bookstack-system-cli +``` + +The CLI is built using PHP. +Depending on operating system and permissions, you may need to instead run it directly via PHP like so: + +```bash +php ./bookstack-system-cli +``` + +By default, without any arguments provided, the CLI will list the available commands which are documented [in more detail below](#available-commands). +With any command, you can pass a `-h` option to show additional per-command details and options. + +--- + +### Standalone Usage + +It's possible to use the CLI without it being part of a BookStack instance. This can be useful if using it to create +a new BookStack install instance. + +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). +Below is how you might fetch the CLI, and make it globally available on the command line, on a Linux server: + +```bash +# Download the raw CLI file from GitHub +curl https://github.com/BookStackApp/BookStack/raw/release/bookstack-system-cli -sLo bookstack-system-cli + +# Made the CLI executable by default +chmod +x bookstack-system-cli + +# Move into a globally accessible PATH location +sudo mv bookstack-system-cli /usr/local/bin/bookstack-system-cli + +# Run the CLI +bookstack-system-cli +``` + +--- + +### Available Commands + +#### backup + +Backup a BookStack installation to a single compressed ZIP file. +By default this will attempt to backup anything that may be expected to be user-generated, or admin edited, within an install. +This includes a database dump of everything within the connected BookStack database instance, along with the current `.env` file in use. +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. + +Note that this won't attempt backup of anything on remote systems, like those uploaded when BookStack is configured to use S3 file storage. + +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 +the BookStack root installation folder, with a name in the format: + +``` +bookstack-backup----