Merge pull request #357 from FilenCloudDienste/dev/unified-commands

"Features" Architecture and Tests

Author: JupiterPi

.dockerignore

@@ -5,3 +5,5 @@ bin-dev
 build
 dist
 node_modules
+.env
+testing

.github/workflows/build-and-publish.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: "23.x"
+          node-version-file: .node-version
       - run: npm ci
       - run: npm run package-${{ matrix.target }}
       - name: Codesign and notarize on macOS
@@ -76,7 +76,7 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v3
-      - name: Set version
+      - name: Inject version
         uses: richardrigutins/replace-in-files@v2
         with:
           files: "package.json"
@@ -85,7 +85,7 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: "23.x"
+          node-version-file: .node-version
           registry-url: "https://registry.npmjs.org"
       - run: npm ci
       - run: npm publish --access public  # includes build
@@ -120,4 +120,44 @@ jobs:
           context: .
           platforms: linux/amd64,linux/arm64
           push: true
-          tags: filen/cli:latest,filen/cli:${{ github.event.release.tag_name }}
+          tags: filen/cli:latest,filen/cli:${{ github.event.release.tag_name }}
+  
+  build-html-docs:
+    name: Build HTML docs
+    runs-on: ubuntu-latest
+    #if: ${{ github.event.release.prerelease == false }}
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Inject version
+        uses: richardrigutins/replace-in-files@v2
+        with:
+          files: "package.json"
+          search-text: "\"version\": \"0.0.0\""
+          replacement-text: "\"version\": \"${{ github.event.release.tag_name }}\""
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
+      - run: npm ci
+      - name: Build filen-cli
+        run: npm run build
+      - name: Build docs
+        run: chmod +x build-docs.sh && ./build-docs.sh
+      - name: Attach HTML file to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: filen-cli-docs.html
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: filen-cli-docs/dist
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/eslint.yml

@@ -27,11 +27,13 @@ jobs:
         uses: actions/checkout@v3
       - name: Setup Node
         uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
       - run: npm ci
       - run: npm run lint-ci
         continue-on-error: true
       - name: Upload analysis results to GitHub
-        uses: github/codeql-action/upload-sarif@v2
+        uses: github/codeql-action/upload-sarif@v3
         with:
           sarif_file: eslint-report.sarif
           wait-for-processing: true

.github/workflows/vitest.yml

@@ -8,10 +8,16 @@ on:
 jobs:
   vitest:
     runs-on: ubuntu-latest
+    env:
+      FILEN_CLI_TESTING_EMAIL: ${{ secrets.V2_TEST_ACC_EMAIL }}
+      FILEN_CLI_TESTING_PASSWORD: ${{ secrets.V2_TEST_ACC_PASS }}
     steps:
       - name: Checkout
         uses: actions/checkout@v3
       - name: Setup Node
         uses: actions/setup-node@v4
+        with:
+          node-version-file: .node-version
       - run: npm ci
-      - run: npm run test
+      - name: Run Vitest
+        run: npm run test

.gitignore

@@ -4,4 +4,5 @@ dist
 .DS_Store
 tmp
 .idea
-key
+.env
+testing

README.md

@@ -3,18 +3,18 @@
 ![Contributors](https://img.shields.io/github/contributors/FilenCloudDienste/filen-cli?color=dark-green) ![Forks](https://img.shields.io/github/forks/FilenCloudDienste/filen-cli?style=social) ![Stargazers](https://img.shields.io/github/stars/FilenCloudDienste/filen-cli?style=social) ![Issues](https://img.shields.io/github/issues/FilenCloudDienste/filen-cli) ![License](https://img.shields.io/github/license/FilenCloudDienste/filen-cli)
 
 The Filen CLI provides a set of useful tools for interacting with the cloud:
-- [Accessing your Filen Drive](#access-your-filen-drive) in a stateless environment or [interactive mode](#interactive-mode)
-- [Syncing](#syncing) locations with the cloud (just like the Desktop app)
-- Mounting a [network drive](#network-drive-mounting)
-- Running a [WebDAV mirror server](#webdav-server) of your [personal drive](#single-user), or multiple drives in [proxy mode](#proxy-mode)
-- Running an [S3 mirror server](#s3-server)
+- Accessing your Filen Drive in a stateless environment or interactive mode
+- Syncing locations with the cloud (just like the Desktop app)
+- Mounting a network drive
+- Running a WebDAV mirror server of your personal drive, or multiple drives in proxy mode
+- Running an S3 mirror server
 
 > [!Note]
 > Please **report bugs** on our [issues page](https://github.com/FilenCloudDienste/filen-cli/issues)! \
 > **Feature requests** can be submitted on [features.filen.io](https://features.filen.io/?tags=cli).
 
 
-# Installation and updates
+## Installation and updates
 
 You can download the latest binaries from the [release page](https://github.com/FilenCloudDienste/filen-cli/releases/latest), or execute the install script (Linux and macOS):
 ```
@@ -23,237 +23,11 @@ curl -sL https://filen.io/cli.sh | bash
 
 Docker images are also available as [filen/cli](https://hub.docker.com/repository/docker/filen/cli) (see [below](#using-docker)).
 
-The Filen CLI includes an automatic updater that checks for a new release every time the CLI is invoked
-(after checking for updates, it will not check again for the next 10 minutes).
-Invoke the CLI with the `--skip-update` flag to skip checking for updates, or use the `--force-update` flag to check for updates even if it was recently checked.
-Use the `--auto-update` flag to skip the confirmation prompt and update automatically (the CLI will still abort after updating).
-
-You can always install any version using `filen install <version>`, `filen install latest` or `filen install canary`.
-
 The CLI is also available as an NPM package, which can be installed with `npm install --global @filen/cli` and then invoked as `filen`. The NPM repository always contains the latest canary releases (see below).
 
-### Canary releases
-
-If you want to be among the first to try out new features and fixes, you can enable canary releases,
-which are early releases meant for a subset of users to test before they are declared as stable.
-To enable or disable canary releases, invoke the CLI with the command `filen canary`.
-
-
-# Usage
-
-```
-$ filen [options...]
-```
-
-Options:
-- `--help`, `-h`: display usage information
-- `--verbose`, `-v`: display additional information
-- `--quiet`, `-q`: hide things like progress bars and additional logs
-- `--email <email>` and `--password <password>` (optionally `--two-factor-code <code>`, `-c <code>`): specify credentials
-- `--log-file <file>`: write logs to a file
-
-### Authenticating
-
-There are several ways to authenticate:
-
-- Invoke the CLI and specify your Filen email and password. You'll have the option to save them in a local encrypted configuration file, which you can delete later using `filen logout`.
-- Invoke the CLI with the `--email` and `--password` (optionally `--two-factor-code`) arguments set.
-- Put your credentials in the `FILEN_EMAIL` and `FILEN_PASSWORD` (optionally `FILEN_2FA_CODE`) environment variables.
-- Store your Filen email and password in a file named `.filen-cli-credentials` where you invoke the CLI. Put your email and password in separate lines, in plain text (optionally 2FA code in third line).
-- Export an "auth config" (which includes your Filen email, password and other details) using `filen export-auth-config`.
-  This will produce a file named `.filen-cli-auth-config`, which the CLI will detect when placed in the data directory or the current working directory.
-  This option can be useful especially for clustered WebDAV/S3 servers, where otherwise too many login requests result in rate limiting.
-
-If you have 2FA enabled and don't specify a 2FA code, you will be prompted for it.
-
-### Data directory
-
-The data directory is where configuration files, credentials, cache etc. are stored and read from. By default, it is `%APPDATA%/filen-cli` (Windows), `~/Library/Application Support/filen-cli` (macOS) or `$XDG_CONFIG_HOME/filen-cli` or `~/.config/filen-cli` (Unix). If there is a directory named `.filen-cli` at the home directory `~`, it is used instead (for instance, the install script installs to this location). You can overwrite the location using the `--data-dir` flag or the `FILEN_CLI_DATA_DIR` environment variable. 
-
-
-## Access your Filen Drive
-
-```
-$ filen [options...] <cmd...>
-```
-
-Options:
-- `--root <path>`, `-r <path`: execute a stateless command from a different working directory
-- `--json`: format output as JSON
-- `--no-autocomplete`: disable autocompletion (for performance or bandwidth reasons)
-
-### Available commands
-
-Many common Unix-style commands are available:
-
-- `ls <path to directory>`: list items inside a directory (pass `-l` for more detailed output)
-- `cat <path to file>`: print content of a text file
-- `head <path to file>` / `tail <path to file>`: print first / last 10 lines of a text file (pass `-n 3` for only 3 lines etc.)
-- `mkdir <path to directory>`: create a directory
-- `rm <path>`: delete a file or directory (`--no-trash` to delete permanently)
-- `stat <path>`: display information about a file or directory
-- `statfs`: display information about your Filen cloud drive
-- `whoami`: print the current user
-- `mv <from> <to>` / `cp <from> <to>`: move or copy a file to a path (parent directory or file)
-
-There are also non-standard commands specific to Filen:
-
-- `download <cloud path> <local destination>`: download a file or directory from the cloud into a local destination
-- `upload <local file> <cloud path>`: upload a local file into the cloud at a specified path
-- `write <file> <content...>`: write text to a file
-- `open <file>`: open a file locally in the associated application
-- `edit <file>`: edit a file locally in the associated application (save and close to re-upload)
-- `view <path>`: view a directory in the Web Drive (you can also invoke `filen drive` to quickly open the Web Drive)
-- `favorites` / `recents`: display favorites or recents
-- `favorite <path>` / `unfavorite <path>`: favorite or unfavorite a file or directory
-
-### Interactive mode
-
-Invoke the Filen CLI without any specified commands to enter interactive mode. 
-There you can specify paths as absolute (starting with `/`) or relative to the current working directory (supports `.` and `..`).
-
-Additional available commands:
-- `help`: display available commands
-- `cd <path>`: navigate to a different path
-- `ls`: list items inside current directory
-- `exit`: exit interactive mode
-
-### Trash
-
-- `filen trash`: view trash items
-- `filen trash restore`: restore a trash item
-- `filen trash delete`: permanently delete a trash item
-- `filen trash empty`: permanently delete all trash items
-
-### Public Links
-
-- `filen links`: view all public links
-- `filen links <path>`: create, view, edit or delete a public link for the given path
-
-### Exporting notes
-
-- `filen export-notes <path>`:
-Exports all Notes to the specified path. If the specified directory doesn't exist, it will be created.
-If it is not empty, a subdirectory will be created with the name "filen-notes-export-\<timestamp\>".
-Richtext notes are exported as HTML. Checklist notes are converted to markdown.
-
-
-## Syncing
-
-```
-$ filen sync [sync pairs...] [--continuous]
-```
-
-Invoke `filen sync` to sync any locations with your Filen Drive. This is the same functionality you get with the Desktop app.
-
-You must specify the sync pairs (`[sync pairs...]` above) as follows:
-- **(central registry)** `filen sync`: Read the sync pairs from `syncPairs.json` (inside the [data dir](#data-directory)). 
-  This file must contain JSON of the type[^type] `{local: string, remote: string, syncMode: string, alias?: string, disableLocalTrash?: boolean, ignore?: string[], excludeDotFiles?: boolean}[]`.
-  `syncMode` can be `twoWay`, `localToCloud`, `localBackup`, `cloudToLocal` or `cloudBackup` (see [here](https://blog.filen.io/how-to-desktop-client/#:~:text=for%20this%20sync.-,Sync%20Modes,-%3A) on what that means). Note that since this is a JSON file, backslashes (`\`) in strings need to be escaped, e. g. `"C:\\some\\path"`).
-- **(custom registry)** `filen sync <file>`: Read the sync pairs from a custom JSON file (same type as above).
-- **(aliases)** `filen sync mypair myotherpair`: Sync the sync pairs from the central registry that were given the aliases `mypair` and `myotherpair`.
-- **(literal pair)** `filen sync /local/path:twoWay:/cloud/path`: Sync the local path `/local/path` with the cloud path `/cloud/path` in two-way sync.
-- **(shorthand for two-way pairs)** `filen sync /local:/cloud`: Sync `/local` with `/cloud` in two-way sync.
-- **(other sync modes and abbreviations)** `filen sync /local1:localToCloud:/cloud1 /local2:ltc:/cloud2`: Sync `/local1` with `/cloud1` (and `/local2` with `/cloud2`) in local-to-cloud sync
-  (other abbreviations are `tw` = `twoWay`, `ltc` = `localToCloud`, `lb` = `localBackup`, `ctl` = `cloudToLocal`, `cb` = `cloudBackup`).
-- **(disable local trash)** `filen sync /local:/cloud --disable-local-trash`: Disable local trash
+The Filen CLI includes an automatic updater, for which you can enable canary releases (if you want to be among the first to try out new features and fixes). You can also install any specific version from within the CLI. See `filen --help updates`.
 
-You can set the `--continuous` flag to keep syncing (instead of only syncing once).
 
-[^type]: This is a [TypeScript type definition](https://www.typescriptlang.org/docs/handbook/2/objects.html), where `?` means an optional field.
+## Documentation
 
-
-## Network drive mounting
-
-```
-$ filen mount [mount point]
-```
-
-Invoke `filen mount` to mount a network drive that mirrors your Filen Drive. The default mount point is `X:` (Windows) / `/tmp/filen` (UNIX).
-
-On Windows, [WinFSP](https://winfsp.dev/rel) needs to be installed. On Linux, [FUSE3](https://github.com/libfuse/libfuse) needs to be installed. On macOS, [FUSE-T](https://www.fuse-t.org/) or [macFUSE](https://osxfuse.github.io/) needs to be installed.
-
-For more information, see also [FilenCloudDienste/filen-network-drive](https://github.com/FilenCloudDienste/filen-virtual-drive).
-
-
-## WebDAV server
-
-You can use the Filen CLI to start a WebDAV server that acts as a mirror server of your Filen Drive.
-
-For more information, see also [FilenCloudDienste/filen-webdav](https://github.com/FilenCloudDienste/filen-webdav).
-
-### Single user
-
-```
-$ filen webdav --w-user <...> --w-password <...> [options...]
-```
-
-Invoke `filen webdav` to start a local WebDAV server that mirrors your personal Filen Drive. 
-This might be useful for allowing local applications to access your Filen Drive via WebDAV.
-
-You must specify login credentials for connecting to the server using the `--w-user` and `--w-password` options (these credentials should be different from your Filen account credentials).
-
-Options:
-
-- `--w-https`: run the server on HTTPS instead of HTTP (using a self-signed certificate)
-- `--w-hostname`: which hostname the server should be started on (default is 0.0.0.0)
-- `--w-port`: which port the server should be started on (default is 80 or 443)
-- `--w-auth-scheme`: the authentication scheme the server should use, "basic" or "digest" (default is basic)
-- `--w-threads`: enables clustering, number of threads to use for the server (default is no clustering; explicitly set to 0 to set by CPU core count).
-  If you experience rate-limiting using this, using an [auth config](#authenticating) might help.
-
-### Proxy mode
-
-```
-$ filen webdav-proxy [options...]
-```
-
-Invoke the `filen webdav-proxy` to start a WebDAV server that allows any user to connect using their Filen account credentials and access their own Filen Drive.
-This might be useful when hosting a proxy server for multiple users. 
-Digest auth is not available for proxy mode.
-
-**Important:** In proxy mode, the password has to be formatted as `password=yoursecretpassword&twoFactorAuthentication=<RECOVERY_CODE_OR_6_DIGIT_OTP_CODE>` (you can also leave out the `&twoFactorAuthentication=...` part if 2FA is disabled for your account).
-
-Options: `--w-https`, `--w-hostname`, `--w-port`, `--w-threads` as above
-
-
-## S3 server
-
-```
-$ filen s3 --s3-access-key-id <...> --s3-secret-access-key <...> [options...]
-```
-
-Invoke `filen s3` to start an S3 server that acts as a mirror server of your Filen Drive.
-You must specify credentials (Access Key ID and Secret Access Key) for connecting to the server using the `--s3-access-key-id` and `--s3-secret-access-key` options (these credentials should be different from your Filen account credentials).
-
-**Important:** When connecting to the S3 server, you need to enable `s3ForcePathStyle` and set the region to `filen`.
-
-For more information, including on S3 compatibility, see also [FilenCloudDienste/filen-s3](https://github.com/FilenCloudDienste/filen-s3).
-
-Options:
-
-- `--s3-https`: run the server on HTTPS instead of HTTP (using a self-signed certificate)
-- `--s3-hostname`: which hostname the server should be started on (default is 0.0.0.0)
-- `--s3-port`: which port the server should be started on (default is 80 or 443)
-- `--s3-threads`: enables clustering, number of threads to use for the server (default is no clustering; explicitly set to 0 to set by CPU core count).
-  If you experience rate-limiting using this, using an [auth config](#authenticating) might help.
-
-## Using Docker
-
-You can run the CLI in a Docker container using the [`filen/cli`](https://hub.docker.com/repository/docker/filen/cli) image.
-
-For example, to run a WebDAV/S3 server in a container, you can use a [Docker Compose](https://docs.docker.com/compose) file similar to this:
-
-```yaml
-services:
-  filen-webdav:
-    image: filen/cli:latest
-    ports:
-      - 80:80
-    command: >
-      --email <...>
-      --password <...>
-      webdav
-      --w-user <...>
-      --w-password <...>
-```
+You can find exhaustive but concise documentation from within the CLI using the `filen --help <cmd or topic>` command and at [docs.cli.filen.io](https://docs.cli.filen.io/). Longer-form documentation is at [docs.filen.io](https://docs.filen.io/docs/cli).