Merge pull request #127 from marcus-crane/write-cli-docs

v1.9.0: Write documentation for CLI tool

.vitepress/config.mts

@@ -54,12 +54,18 @@ export default defineConfig({
           { text: 'Linux', link: '/installation/linux' }
         ]
       },
+      {
+        text: 'Advanced',
+        items: [
+          { text: 'October CLI', link: '/user-guide/advanced/cli' },
+          { text: 'Reading Formats', link: '/user-guide/advanced/reading-formats' },
+        ]
+      },
       {
         text: 'Extras',
         items: [
           { text: 'Changelog', link: '/changelog' },
-          { text: 'LICENSE', link: '/miscellaneous/license' },
-          { text: 'Reading Formats', link: '/miscellaneous/reading-formats' },
+          { text: 'Software License', link: '/license' },
           { text: 'Thanks', link: '/thanks' }
         ]
       }

docs/changelog.md

@@ -1,8 +1,25 @@
----
----
-
 # Changelog
 
+## v1.9.0
+
+This release introduces a command line interface (CLI) for power users of October, who prefer to sync highlights without opening the desktop UI.
+
+Users of automation software may also find this handy for automatically triggering a sync when their automation software detects that a Kobo is connected.
+
+At the moment, it just has basic sync functionality with settings still powered by the UI but eventually it'll be brought up to feature parity with the rest of the desktop UI.
+
+![](./public/macos/macos_cli.png)
+
+This release also brings official support for the following newer devices:
+
+- Clara 2E
+- Elipsa 2E
+- Libra Colour
+- Clara BW
+- Clara Colour
+
+Functionally, they should have always worked but the UI will now recognise their model names.
+
 ## v1.8.0
 
 This release adds support for Linux machines running arm64 such as newer Raspberry Pi devices apparently.

docs/miscellaneous/license.md → docs/license.md

@@ -1,4 +1,8 @@
-# License
+# Software License
+
+October is released under the MIT License which is replicated below from the [source file](https://github.com/marcus-crane/october/blob/main/LICENSE).
+
+---
 
 MIT License
 

docs/user-guide/advanced/cli.md

@@ -0,0 +1,150 @@
+# October CLI
+
+As of [v1.9.0](http://localhost:5173/changelog#v1-9-0), October ships with a [CLI interface](https://en.wikipedia.org/wiki/Command-line_interface).
+
+If you are unfamiliar with that means, it's probably not the right tool for you and you can continue to use the existing desktop app as normal.
+
+For those who consider themselves power users, you can use the CLI to quickly sync bookmarks without having to boot up the desktop app and click around.
+
+>[!WARNING]
+> At the time of writing, the CLI syncs highlights and that's about it.
+>
+> The output has been left in a messy state in order to ship something out. It will be brought up to feature parity eventually.
+>
+> Settings can only be configured via the desktop app in the meantime.
+
+In order to keep distribution easy, and to keep the filesize of October small, the desktop app and CLI app are bundled together rather than being two separate binaries.
+
+The CLI is invoked explicitly with a subcommand, in order to maintain standard OS behaviours when executing binaries, even if it admittedly feels a little weird.
+
+This also ensures that automation tools such as [Keyboard Maestro](https://www.keyboardmaestro.com/) should work with the October CLI where their execution environments don't look like a traditional terminal, so it's better to be explicit than try and guess user intent.
+
+Here is an exhaustive list of supported commands at the time of writing:
+
+```console
+$ october cli help
+$ october cli sync
+```
+
+With all that out of the way, here are some examples of how to use it for the various platforms that October supports.
+
+## Platform usage
+
+### Windows
+
+For Windows, the executable for October lives at `C:\Program Files\utf9k\October\October.exe`.
+
+Here's an example of it in use:
+
+```powershell
+PS C:\Users\marcus\Desktop> & 'C:\Program Files\utf9k\October\October.exe' cli sync
+time="2024-06-10T18:46:58+12:00" level=info msg="Found an attached device" device_id=00000000-0000-0000-0000-000000000384
+time="2024-06-10T18:46:58+12:00" level=info msg="Successfully parsed highlights" batch_count=1 highlight_count=248
+time="2024-06-10T18:47:02+12:00" level=info msg="Successfully sent bookmarks to Readwise" batch_count=1
+time="2024-06-10T18:47:02+12:00" level=info msg="Successfully synced 248 highlights to Readwise"
+```
+
+You may prefer to add the CLI folder to your PATH for easier access eg;
+
+```powershell
+PS C:\Users\marcus\Desktop> $env:PATH += ";C:\Program Files\utf9k\October"
+PS C:\Users\marcus\Desktop> October.exe cli
+NAME:
+   october cli - sync your kobo highlights to readwise from your terminal
+
+USAGE:
+   october cli [global options] command [command options]
+
+VERSION:
+   v1.9.0
+
+AUTHOR:
+   Marcus Crane <october@utf9k.net>
+
+COMMANDS:
+   sync, s  sync kobo highlights to readwise
+   help, h  Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --help, -h     show help
+   --version, -v  print the version
+```
+
+### macOS
+
+For macOS, the executable for October lives at `/Applications/October.app/Contents/MacOS/October`.
+
+Here's an example of it in use:
+
+```console
+/Applications/October.app/Contents/MacOS/October cli sync
+INFO[0000] Found an attached device                      device_id=00000000-0000-0000-0000-000000000384
+INFO[0000] Successfully parsed highlights                batch_count=1 highlight_count=248
+INFO[0001] Successfully sent bookmarks to Readwise       batch_count=1
+INFO[0001] Successfully synced 248 highlights to Readwise
+```
+
+You may prefer to add the CLI folder to your PATH for easier access eg;
+
+```console
+$ export PATH=$PATH:/Applications/October.app/Contents/MacOS
+$ october cli help
+NAME:
+   october cli - sync your kobo highlights to readwise from your terminal
+
+USAGE:
+   october cli [global options] command [command options]
+
+VERSION:
+   v1.9.0
+
+AUTHOR:
+   Marcus Crane <october@utf9k.net>
+
+COMMANDS:
+   sync, s  sync kobo highlights to readwise
+   help, h  Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --help, -h     show help
+   --version, -v  print the version
+```
+
+### Linux
+
+For Linux, the executable for October lives at `/usr/local/bin`.
+
+Here's an example of it in use:
+
+```console
+$ october cli sync
+INFO[0000] Found an attached device                      device_id=00000000-0000-0000-0000-000000000384
+INFO[0000] Successfully parsed highlights                batch_count=1 highlight_count=248
+INFO[0001] Successfully sent bookmarks to Readwise       batch_count=1
+INFO[0001] Successfully synced 248 highlights to Readwise
+```
+
+The CLI tool should already be in your path by default on any modern Linux system:
+
+```console
+$ october cli help
+NAME:
+   october cli - sync your kobo highlights to readwise from your terminal
+
+USAGE:
+   october cli [global options] command [command options]
+
+VERSION:
+   v1.9.0
+
+AUTHOR:
+   Marcus Crane <october@utf9k.net>
+
+COMMANDS:
+   sync, s  sync kobo highlights to readwise
+   help, h  Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --help, -h     show help
+   --version, -v  print the version
+```