Separate desktop application and CLI docs, extend CLI argument texts

2026-08-14 13:45:27 +02:00 · 2025-10-03 20:25:15 +02:00
parent 1843eeabed
commit c4b66a1e76
16 changed files with 327 additions and 134 deletions
@@ -0,0 +1,43 @@
+<!--
+    SPDX-FileCopyrightText: 2025 Simon Repp
+    SPDX-License-Identifier: CC0-1.0
+-->
+
+# Preface and overview of the command line interface
+
+> Heads up: If you're not familiar with command line interfaces, this section
+  is likely not relevant for you, as it's primarily intended for people who
+  are already
+> familiar with them. However, if you're curious to explore new technical
+> skills and possibilities, you are still warmly invited to read it! In the
+  worst
+> case it will be confusing and/or boring, but in the best case it might
+> introduce you to a new, powerful way of working with computers.
+
+At its core, the command line interface provides exactly the same
+functionality as the desktop application - it is neither less powerful nor
+less rich in features, instead it just provides different workflows that the
+graphical interface can not offer (such as automation and scripting).
+
+The command line interface provides the following functionality:
+
+- Without any specific options passed, the CLI will start a **web server**
+  that hosts the Hyper 8 editor, which you (and, if you want, others)
+  can use through a browser. The options `--ip`, `--port` and
+  `--workers` can be used to set the server configuration.
+
+- The options `--build`/`-b` (optionally paired with `--preview`/`-p`) and
+  `--deploy`/`-d` can be used to perform the respective actions directly
+  from the CLI (without the graphical editor). The optional `--preview`
+  flag interacts with the `--ip` and `--port` options to determine the
+  preview server configuration.
+
+- The options `--build-dir` and `--cache-dir` let you manually override
+  to which directory Hyper 8 writes the build (or respectively) cache
+  files.
+
+  **WARNING: Both directories are WIPED during the build process.**<br>
+  Please pay very close attention where you point them to.
+
+  (By default, build and cache files are written to `.hyper8_build/`
+  and `.hyper8_cache/` inside the root of your site directory)
@@ -0,0 +1,83 @@
+<!--
+    SPDX-FileCopyrightText: 2024-2025 Simon Repp
+    SPDX-License-Identifier: CC0-1.0
+-->
+
+# Installation and usage
+
+You can download and install either the full desktop edition
+or the command line edition from the
+[download page](https://simonrepp.com/hyper8/download.html) – **both include
+the command line interface**.
+
+All remaining sections on this page will assume that you already have a
+[site directory](introduction.html) to work with - if you don't, you can
+simply create an empty folder on your disk (anywhere you like), for instance
+by running the command below, and that will be your site directory:
+
+```bash
+mkdir my-site-dir
+```
+
+## Running the editor
+
+Simply pass the site directory path to `hyper8` and it will start a web server
+hosting the graphical editor. You can open the displayed address in your
+browser and then perform every action that the desktop application provides
+as well (authoring, previewing, building and deploying your site).
+
+```bash
+hyper8 my-site-dir
+```
+
+You can press `Ctrl+C` to shut down the editor at any point.
+
+## Building (and previewing) the site
+
+The `--build` option (short: `-b`) will build the site:
+
+```bash
+hyper8 my-site-dir --build
+```
+
+With the added `--preview` flag (short: `-p`) the site will be opened in the browser afterwards:
+
+```bash
+hyper8 my-site-dir --build --preview
+```
+
+## Deploying the site
+
+If you've already set up a deployment configuration for your site you can deploy it straight from the command line interface by adding the `--deploy` (short: `-d`) option:
+
+```bash
+hyper8 my-site-dir --build --deploy
+```
+
+## Manually setting the build directory
+
+By default, Hyper 8 will generate the site inside a `.hyper8_build/` directory
+that is placed at the root of your site directory (e.g. `my-site-dir/.hyper8_build/`).
+
+If you want to build (or if you will, *locally deploy*) the site to another directory
+on your disk you can pass an option to do so, but please read the warning first:
+
+**WARNING: The build directory gets WIPED during each build. Specifying the wrong
+directory can lead to severe loss of data, so triple check what you pass here.**
+
+With that covered, here is the magic option to override the build directory:
+
+```bash
+hyper8 my-site-dir --build --build-dir [danger-this-path-will-be-wiped]
+```
+
+## Using Hyper 8 without the graphical editor
+
+You can populate and configure your site by putting content in
+your site directory, using solely your file browser, text editor, terminal,
+custom scripts, or whichever workflow you aim for or prefer.
+
+How this works is thoroughly explained in the [Site directory specification](introduction.html)
+and [Site directory examples](single-video-only.html) sections. For a quick
+introduction there is also a video showcasing the process at
+[simonrepp.com/video/hyper8/without-editor](https://simonrepp.com/video/hyper8/without-editor).
@@ -0,0 +1,71 @@
+<!--
+    SPDX-FileCopyrightText: 2024-2025 Simon Repp
+    SPDX-License-Identifier: CC0-1.0
+-->
+
+# Argument reference
+
+General usage is:
+
+```
+hyper8 [OPTIONS] [SITE_DIR]
+```
+
+If you are using the **full desktop edition** of Hyper 8, calling `hyper8`
+without any arguments starts the graphical launcher (and conversely, passing
+any argument at all enables command line mode).
+
+If you are using the **command line edition** of Hyper 8, the `SITE_DIR`
+argument is mandatory, and not passing any argument at all will just print
+the usage information.
+
+## Options
+
+- `--build`, `-b`
+
+  Directly builds the site without starting the editor
+
+- `--build-dir <BUILD_DIR>`
+
+  The path to which the deployable, built site is written.
+
+  **WARNING: This directory is WIPED during the build process.**<br>
+  Please pay very close attention where you point this to.
+
+  (Default location: .hyper8_build/ inside the site directory).
+
+- `--cache-dir <CACHE_DIR>`
+
+  The path at which all computational results (computed metadata, resized images, temporary encoding artifacts) are stored.
+
+  **WARNING: This directory may be WIPED during the build process.**<br>
+  Please pay very close attention where you point this to.
+
+  (Default location: .hyper8_cache/ inside the site directory)
+
+- `--deploy`, `-d`
+
+  Directly deploys the site - only applicable in combination with `--build`
+
+- `--ip <IP>`
+
+  Manually sets the ip address used by the editor or preview server (otherwise defaults to localhost)
+
+- `--port <PORT>`
+
+  Manually sets the port used by the editor or preview server (otherwise chooses an available port on its own)
+
+- `--preview`, `-p`
+
+  Use in conjunction with `--build` to immediately open the site in the browser after the build is complete
+
+- `--workers <COUNT>`
+
+  Set how many background workers should be run. The count can be no less than 2 - one worker for fast jobs (video analysis, thumbnails), one worker for slow jobs (audio/video transcoding).
+
+## Note on accuracy
+
+This page will generally be kept up-to-date with Hyper 8's latest CLI usage
+information, but for the most authoritative and up-to-date information it is
+still recommended to just consult `hyper8 --help` for your installed
+version.