syntaxis/docs/config.md

# 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)