From 57bc8cd9c021feaf08e139e8fb62800bc476068e Mon Sep 17 00:00:00 2001
From: DanConwayDev <DanConwayDev@protonmail.com>
Date: Wed, 3 Dec 2025 11:17:39 +0000
Subject: improved settings cli flags > env vars > defaults

---
 .env.example | 101 ++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 79 insertions(+), 22 deletions(-)

(limited to '.env.example')

diff --git a/.env.example b/.env.example
index 796415e..0a93b1f 100644
--- a/.env.example
+++ b/.env.example
@@ -1,34 +1,91 @@
 # ngit-grasp Configuration
+#
+# Configuration Priority (highest to lowest):
+# 1. CLI flags (e.g., --domain example.com)
+# 2. Environment variables (e.g., NGIT_DOMAIN=example.com)  
+# 3. This .env file
+# 4. Built-in defaults
+#
+# Run `ngit-grasp --help` for all CLI options
 
-# Domain where this instance is hosted (used in GRASP validation)
-NGIT_DOMAIN=gitnostr.com
+# ============================================================================
+# REQUIRED
+# ============================================================================
 
-# Owner's npub (for relay info)
-NGIT_OWNER_NPUB=npub1...
+# Domain where this instance is hosted (required, used in GRASP validation)
+# CLI: --domain <domain>
+# No default - must be set
+# NGIT_DOMAIN=
 
-# Relay information (NIP-11)
-NGIT_RELAY_NAME=My GRASP Relay
-NGIT_RELAY_DESCRIPTION=A GRASP-compliant Git relay with Nostr authorization
+# ============================================================================
+# SERVER CONFIGURATION
+# ============================================================================
 
-# Storage paths
-NGIT_GIT_DATA_PATH=./data/git
-NGIT_RELAY_DATA_PATH=./data/relay
+# Server bind address (IP:PORT)
+# CLI: --bind-address <address>
+# Default: 127.0.0.1:8080
+# NGIT_BIND_ADDRESS=127.0.0.1:8080
 
-# Database backend (memory, nostrdb, lmdb)
-# - memory: In-memory database (default, fastest, no persistence)
-# - nostrdb: NostrDB backend (persistent, optimized for Nostr) [Not yet implemented]
-# - lmdb: LMDB backend (persistent, general purpose)
-NGIT_DATABASE_BACKEND=memory
+# ============================================================================
+# RELAY INFORMATION (NIP-11)
+# ============================================================================
 
-# Server configuration
-NGIT_BIND_ADDRESS=127.0.0.1:8080
+# Owner's npub (optional, for relay info in NIP-11)
+# CLI: --owner-npub <npub>
+# Default: (none)
+# NGIT_OWNER_NPUB=npub1...
 
-# Logging
-RUST_LOG=info
+# Relay name shown in NIP-11 information document
+# CLI: --relay-name <name>
+# Default: ${domain} grasp relay (e.g., "gitnostr.com grasp relay")
+# NGIT_RELAY_NAME=My GRASP Relay
 
-# Optional: Proactive sync settings (GRASP-02)
+# Relay description shown in NIP-11 information document
+# CLI: --relay-description <description>
+# Default: Git Nostr Relay - a grasp implementation
+# NGIT_RELAY_DESCRIPTION="A GRASP-compliant Git relay with Nostr authorization"
+
+# ============================================================================
+# STORAGE
+# ============================================================================
+
+# Path to store Git repositories
+# CLI: --git-data-path <path>
+# Default: ./data/git
+# NGIT_GIT_DATA_PATH=./data/git
+
+# Path to store Nostr relay data
+# CLI: --relay-data-path <path>
+# Default: ./data/relay
+# NGIT_RELAY_DATA_PATH=./data/relay
+
+# Database backend for Nostr events
+# CLI: --database-backend <backend>
+# Options: lmdb, memory, nostrdb
+# Default: lmdb
+#   - lmdb: LMDB backend (persistent, general purpose) - RECOMMENDED
+#   - memory: In-memory database (fastest, no persistence, uses temp dirs)
+#   - nostrdb: NostrDB backend (persistent, Nostr-optimized) [Not yet implemented]
+#
+# Note: When using 'memory' backend, git_data_path and relay_data_path
+# are automatically set to temporary directories for ephemeral testing.
+# NGIT_DATABASE_BACKEND=lmdb
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+# Rust log level (not a ngit-grasp config, but useful for debugging)
+# Options: error, warn, info, debug, trace
+# RUST_LOG=info
+
+# ============================================================================
+# FUTURE/PLANNED OPTIONS (not yet implemented)
+# ============================================================================
+
+# Proactive sync settings (GRASP-02)
 # NGIT_PROACTIVE_SYNC_ENABLED=true
 # NGIT_PROACTIVE_SYNC_INTERVAL_SECS=3600
 
-# Optional: Archive mode (GRASP-05)
-# NGIT_ARCHIVE_MODE=false
+# Archive mode (GRASP-05)
+# NGIT_ARCHIVE_MODE=false
\ No newline at end of file
-- 
cgit v1.2.3