# Configuration Guide Complete reference for configuring SYNTAXIS components. ## Configuration Location All configuration files are in: `~/.config/syntaxis/` ```bash ~/.config/syntaxis/ ├── syntaxis-cli.toml # CLI settings ├── syntaxis-tui.toml # TUI keybindings and colors ├── syntaxis-api.toml # API server configuration ├── database-default.toml # SQLite settings ├── database-surrealdb.toml # SurrealDB settings (optional) └── api/features/ # Optional feature configs ├── auth.toml.template ├── database.toml.template ├── logging.toml.template └── metrics.toml.template ``` ## Environment Variables Set these before running SYNTAXIS: ```bash # Core settings export SYNTAXIS_CONFIG_DIR="$HOME/.config/syntaxis" export SYNTAXIS_DATA_DIR="$HOME/.local/share/syntaxis" # Database selection export SYNTAXIS_DATABASE="default" # or "surrealdb" # Logging export RUST_LOG="debug" # or "info", "warn", "error" # API server export SYNTAXIS_API_PORT=3000 export SYNTAXIS_API_HOST=127.0.0.1 ``` --- ## CLI Configuration (syntaxis-cli.toml) ```toml [general] # Output format: json, yaml, table, plain output_format = "table" # Enable verbose output verbose = false # Color output use_colors = true [database] # Database backend: sqlite (default) or surrealdb backend = "sqlite" # SQLite file location (relative to SYNTAXIS_DATA_DIR) sqlite_path = "syntaxis.db" [api] # Connect to remote API server (optional) # If not set, uses local database server_url = "" # e.g., "http://localhost:3000" [pagination] # Default items per page items_per_page = 20 ``` ### Common Settings - `output_format`: Output style for list commands (table shows columns, json is machine-readable) - `verbose`: Show detailed output for all commands - `use_colors`: Colorize output (disable on systems without color support) --- ## TUI Configuration (syntaxis-tui.toml) ### Navigation Keybindings ```toml [keybindings] # Navigation (vim-style by default) move_up = "k" move_down = "j" move_left = "h" move_right = "l" # Actions select = "Enter" insert = "i" edit = "e" delete = "d" save = ":w" quit = ":q" search = "/" ``` ### Colors ```toml [colors] # Color scheme: light, dark, solarized theme = "dark" # Specific colors (ANSI or hex) [colors.foreground] default = "white" success = "green" warning = "yellow" error = "red" info = "blue" [colors.background] default = "black" highlight = "dark_gray" ``` ### Behavior ```toml [behavior] # Enable mouse support enable_mouse = true # Auto-save on exit auto_save = true # Confirm before delete confirm_delete = true # Show help on startup show_help = false # Default view on startup startup_view = "projects" ``` --- ## API Configuration (syntaxis-api.toml) ### Server Settings ```toml [server] # Listen address and port host = "127.0.0.1" port = 3000 # Enable CORS for web dashboards cors_enabled = true cors_origins = ["http://localhost:8080", "http://localhost:3000"] # Request logging log_requests = true # Max request body size (bytes) max_body_size = 1048576 # 1 MB ``` ### Database Configuration ```toml [database] # Backend: sqlite (default) or surrealdb backend = "sqlite" [database.sqlite] # SQLite file path path = "syntaxis.db" # Connection pool size pool_size = 5 # Enable WAL mode for better concurrency wal_mode = true [database.surrealdb] # SurrealDB connection URL url = "file:///tmp/syntaxis.db" # or "http://localhost:8000" # Authentication username = "root" password = "root" # Database namespace and name namespace = "syntaxis" database = "syntaxis" ``` ### Features ```toml [features] # Enable authentication auth_enabled = false # Enable API metrics metrics_enabled = true # Enable request logging logging_enabled = true ``` ### Performance ```toml [performance] # Request timeout (seconds) request_timeout = 30 # Cache TTL (seconds) cache_ttl = 300 # Max concurrent requests max_concurrent = 100 # Connection pool size pool_size = 10 ``` --- ## Database Configuration ### SQLite (Default) SQLite is the default database backend, ideal for single-user and small team deployments: ```toml [database] type = "sqlite" path = "syntaxis.db" [database.connection] pool_size = 5 max_connections = 20 wal_mode = true # Write-Ahead Logging for concurrency journal_mode = "WAL" synchronous = "NORMAL" # Balance between safety and speed [migrations] auto_migrate = true # Run migrations automatically on startup ``` **When to use SQLite**: - Single developer workflows - Local development - Small team collaboration (< 5 users) ### SurrealDB (Optional) SurrealDB provides multi-backend support for team deployments: ```toml [database] type = "surrealdb" url = "file:///path/to/db" # or "http://localhost:8000" namespace = "syntaxis" database = "syntaxis" [credentials] username = "root" password = "root" [connection] pool_size = 10 timeout = 30 tls_enabled = false # Enable for production remote connections ``` **When to use SurrealDB**: - Team deployments - Multi-user concurrent access - Remote database servers - Kubernetes/container deployments --- ## Configuration Best Practices ### Development Setup ```toml # syntaxis-cli.toml (dev) output_format = "table" verbose = true use_colors = true # syntaxis-api.toml (dev) log_requests = true cors_origins = ["http://localhost:3000", "http://localhost:8080"] [features] metrics_enabled = true logging_enabled = true ``` ### Production Setup ```toml # syntaxis-cli.toml (prod) output_format = "json" verbose = false # syntaxis-api.toml (prod) cors_origins = ["https://app.example.com"] auth_enabled = true log_requests = false # Reduce overhead [performance] request_timeout = 60 pool_size = 20 ``` --- ## Customization Examples ### Change Database Backend Switch from SQLite to SurrealDB: 1. **Edit syntaxis-cli.toml**: ```toml [database] backend = "surrealdb" ``` 2. **Edit syntaxis-api.toml**: ```toml [database] backend = "surrealdb" [database.surrealdb] url = "http://localhost:8000" username = "root" password = "root" ``` 3. **Start SurrealDB server** (separate process): ```bash surreal start --bind 127.0.0.1:8000 file:///tmp/syntaxis.db ``` 4. **Restart applications**: ```bash syntaxis-api ``` ### Enable API Authentication 1. **Copy auth template**: ```bash cp ~/.config/syntaxis/api/features/auth.toml.template \ ~/.config/syntaxis/api/features/auth.toml ``` 2. **Set a secure secret**: ```bash # Edit auth.toml and set a strong secret (e.g., generate with: openssl rand -hex 32) ``` 3. **Enable in syntaxis-api.toml**: ```toml [features] auth_enabled = true ``` ### Change API Port ```bash # Edit syntaxis-api.toml [server] port = 8000 # Or use environment variable export SYNTAXIS_API_PORT=8000 syntaxis-api ``` --- ## Verification ### Check Configuration Files ```bash # List all config files ls ~/.config/syntaxis/ # View a configuration cat ~/.config/syntaxis/syntaxis-cli.toml ``` ### Validate TOML Syntax ```bash # Check for syntax errors (with rust installed) cargo install toml-lint toml-lint ~/.config/syntaxis/*.toml ``` ### Test with Applications ```bash # Test CLI syntaxis-cli --debug project list # Test TUI syntaxis-tui # Test API syntaxis-api & curl http://localhost:3000/health ``` --- ## Troubleshooting Configuration ### Config Files Not Found ```bash # Create config directory mkdir -p ~/.config/syntaxis # Copy from bundle cp configs/*.toml ~/.config/syntaxis/ ``` ### Invalid TOML Syntax Check for common issues: - Missing quotes around string values - Mismatched brackets `[section]` vs `[[array]]` - Invalid characters or control codes - Tabs vs spaces (TOML requires spaces) Fix by editing with a text editor: ```bash nano ~/.config/syntaxis/syntaxis-cli.toml ``` ### Changes Not Applied Configuration is loaded at startup: ```bash # Restart the application pkill syntaxis-api sleep 2 syntaxis-api # Or explicitly set config directory export SYNTAXIS_CONFIG_DIR=~/.config/syntaxis syntaxis-api ``` --- ## Next Steps - See [QUICK_START.md](QUICK_START.md) for basic usage - See [docs/installation.md](docs/installation.md) for installation help - See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues - Visit https://doc.syntaxis.dev for online documentation --- **SYNTAXIS** v0.1.0 • [syntaxis.dev](https://syntaxis.dev)