From f6e12df2bf0319cb2f1cafd8982c7bc87e1a706a Mon Sep 17 00:00:00 2001 From: Allison Truhlar Date: Thu, 23 Apr 2026 14:03:39 -0400 Subject: [PATCH 1/2] feat: allow adding file share mounts via cli params --- fileglancer/cli.py | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/fileglancer/cli.py b/fileglancer/cli.py index 141b59e33..94b3e9b30 100644 --- a/fileglancer/cli.py +++ b/fileglancer/cli.py @@ -130,10 +130,19 @@ def cli(): help='Automatically find an available port if the specified port is in use.') @click.option('--no-browser', is_flag=True, default=False, help='Do not open web browser automatically.') +@click.option('--file-share-mounts', '-f', multiple=True, + help='File share path to mount (can be specified multiple times). ' + 'Use ~/ prefix for home directory. Overrides config file setting.') def start(host, port, reload, workers, ssl_keyfile, ssl_certfile, - ssl_ca_certs, ssl_version, ssl_cert_reqs, ssl_ciphers, timeout_keep_alive, auto_port, no_browser): + ssl_ca_certs, ssl_version, ssl_cert_reqs, ssl_ciphers, timeout_keep_alive, auto_port, no_browser, + file_share_mounts): """Start the Fileglancer server using uvicorn.""" + # Set file share mounts from CLI if provided + if file_share_mounts: + os.environ['FGC_FILE_SHARE_MOUNTS'] = json.dumps(list(file_share_mounts)) + logger.debug(f"Setting FGC_FILE_SHARE_MOUNTS={os.environ['FGC_FILE_SHARE_MOUNTS']}") + # Set up default external proxy URL if not already configured # Need to set this before loading settings as it is required in the Settings model if 'FGC_EXTERNAL_PROXY_URL' not in os.environ: From 4229fe1f7c10f8e293e7f8ab225f16b5d3e263c7 Mon Sep 17 00:00:00 2001 From: Allison Truhlar Date: Thu, 30 Apr 2026 15:58:49 -0400 Subject: [PATCH 2/2] docs: add basic instructions for using the CLI tool --- docs/CLI.md | 155 +++++++++++++++++++++++++++++++++++++++++++++ fileglancer/cli.py | 10 ++- 2 files changed, 162 insertions(+), 3 deletions(-) create mode 100644 docs/CLI.md diff --git a/docs/CLI.md b/docs/CLI.md new file mode 100644 index 000000000..0ecd9d3de --- /dev/null +++ b/docs/CLI.md @@ -0,0 +1,155 @@ +# Fileglancer CLI + +The `fileglancer` command-line tool starts a local Fileglancer server for browsing and managing files on your machine. + +## Installation + +The best practice is to install Fileglancer into a dedicated environment using your preferred Python package manager, e.g., [Pixi](https://pixi.prefix.dev/dev/installation/) or [uv](https://docs.astral.sh/uv/getting-started/installation/): + +```bash +# pixi +pixi add fileglancer + +# uv +uv venv fileglancer-env +source fileglancer-env/bin/activate +uv pip install fileglancer +``` + +If you have uv installed and want a quick one-liner to try Fileglancer in a temporary environment: + +```bash +uvx fileglancer start +``` + +## Start Fileglancer + +From inside the environment you just created, run: + +```bash +fileglancer start +``` + +This starts the server on `http://127.0.0.1:8000`, opens your browser, and serves your home directory by default. + +## Configuration + +Fileglancer looks for configuration in the current working directory. Settings are loaded from multiple sources, in priority order (highest first): + +1. **CLI flags** (e.g., `--port 9000`) +2. **Environment variables** — prefixed with `FGC_` (case-insensitive) +3. **`.env` file** — in the current directory +4. **`config.yaml`** — in the current directory + +If no configuration is found, sensible defaults are used. + +### Using a config file + +Create a `config.yaml` in the directory you plan to run `fileglancer start` from: + +```yaml +# Directories to expose in the file browser +file_share_mounts: + - "~/" + - /data/shared + +# Logging level (ERROR, WARNING, INFO, DEBUG, TRACE) +log_level: INFO + +# Database URL (defaults to ~/.local/share/fileglancer/fileglancer.db) +db_url: sqlite:///fileglancer.db + +# External proxy URL for shared file links +external_proxy_url: http://localhost:8000/files +``` + +A full template with all available options is available at [`docs/config.yaml.template`](config.yaml.template) in the source repository. + +### Using environment variables + +Any setting can also be set via an environment variable with the `FGC_` prefix: + +```bash +export FGC_LOG_LEVEL=DEBUG +export FGC_FILE_SHARE_MOUNTS='["~/data", "/shared/images"]' +export FGC_DB_URL='sqlite:///my-fileglancer.db' +``` + +For nested settings (like cluster configuration), use `__` as a delimiter: + +```bash +export FGC_CLUSTER__EXECUTOR=lsf +export FGC_CLUSTER__QUEUE=normal +``` + +### Using a .env file + +You can also place environment variables in a `.env` file in the current directory: + +``` +FGC_LOG_LEVEL=DEBUG +FGC_DB_URL=sqlite:///fileglancer.db +``` + +## Command Reference + +### `fileglancer start` + +Start the Fileglancer server. Run `fileglancer start --help` to see all available options. + +```bash +fileglancer start [OPTIONS] +``` + +#### Options + +| Option | Default | Description | +|--------|---------|-------------| +| `--host` | `127.0.0.1` | Host address to bind to | +| `--port` | `8000` | Port to bind to | +| `-f` / `--file-share-mounts` | — | File share path to mount (repeatable) | +| `--no-browser` | off | Don't open a browser automatically | +| `--auto-port` | `true` | Find an available port if the specified one is in use | +| `--reload` | off | Enable auto-reload on code changes | +| `--workers` | — | Number of worker processes | +| `--ssl-keyfile` | — | Path to SSL private key file | +| `--ssl-certfile` | — | Path to SSL certificate file | +| `--ssl-ca-certs` | — | Path to CA certificates file | +| `--ssl-ciphers` | `TLSv3` | SSL ciphers to use | +| `--timeout-keep-alive` | `5` | Keep-alive timeout in seconds | + +#### Examples + +Start with defaults (serves home directory on port 8000): + +```bash +fileglancer start +``` + +Serve specific directories: + +```bash +fileglancer start -f ~/projects -f /data/shared +``` + +Start on a specific port without opening a browser: + +```bash +fileglancer start --port 9000 --no-browser +``` + +Start with HTTPS: + +```bash +fileglancer start --ssl-keyfile /path/to/key.pem --ssl-certfile /path/to/cert.pem +``` + +## Data Storage + +By default, Fileglancer stores its database at: + +``` +~/.local/share/fileglancer/fileglancer.db +``` + +This can be overridden with the `db_url` setting in `config.yaml` or the `FGC_DB_URL` environment variable. diff --git a/fileglancer/cli.py b/fileglancer/cli.py index 94b3e9b30..cc8ad5f7f 100644 --- a/fileglancer/cli.py +++ b/fileglancer/cli.py @@ -112,6 +112,12 @@ def cli(): help='Enable auto-reload.') @click.option('--workers', default=None, type=int, help='Number of worker processes.') +@click.option('--file-share-mounts', '-f', multiple=True, + help='File share path to mount (can be specified multiple times). ' + 'If you have many mounts, it is easier to set these via the config file. ' + 'File share paths specified here will override the config file setting. ' + 'Use ~/ prefix for home directory.' + ) @click.option('--ssl-keyfile', type=click.Path(exists=True), help='SSL key file path.') @click.option('--ssl-certfile', type=click.Path(exists=True), @@ -130,9 +136,7 @@ def cli(): help='Automatically find an available port if the specified port is in use.') @click.option('--no-browser', is_flag=True, default=False, help='Do not open web browser automatically.') -@click.option('--file-share-mounts', '-f', multiple=True, - help='File share path to mount (can be specified multiple times). ' - 'Use ~/ prefix for home directory. Overrides config file setting.') + def start(host, port, reload, workers, ssl_keyfile, ssl_certfile, ssl_ca_certs, ssl_version, ssl_cert_reqs, ssl_ciphers, timeout_keep_alive, auto_port, no_browser, file_share_mounts):