syntaxis/docs/config.md

Configuration Guide

Complete reference for configuring SYNTAXIS components.

Configuration Location

All configuration files are in: ~/.config/syntaxis/

~/.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:

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

[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

[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

[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

[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

[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

[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

[features]
# Enable authentication
auth_enabled = false

# Enable API metrics
metrics_enabled = true

# Enable request logging
logging_enabled = true

Performance

[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:

[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:

[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

# 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

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

[database]
backend = "surrealdb"

2. Edit syntaxis-api.toml:

[database]
backend = "surrealdb"

[database.surrealdb]
url = "http://localhost:8000"
username = "root"
password = "root"

3. Start SurrealDB server (separate process):

surreal start --bind 127.0.0.1:8000 file:///tmp/syntaxis.db

4. Restart applications:

syntaxis-api

Enable API Authentication

1. Copy auth template:

cp ~/.config/syntaxis/api/features/auth.toml.template \
   ~/.config/syntaxis/api/features/auth.toml

2. Set a secure secret:

# Edit auth.toml and set a strong secret (e.g., generate with: openssl rand -hex 32)

3. Enable in syntaxis-api.toml:

[features]
auth_enabled = true

Change API Port

# Edit syntaxis-api.toml
[server]
port = 8000

# Or use environment variable
export SYNTAXIS_API_PORT=8000
syntaxis-api

---

Verification

Check Configuration Files

# List all config files
ls ~/.config/syntaxis/

# View a configuration
cat ~/.config/syntaxis/syntaxis-cli.toml

Validate TOML Syntax

# Check for syntax errors (with rust installed)
cargo install toml-lint
toml-lint ~/.config/syntaxis/*.toml

Test with Applications

# 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

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

nano ~/.config/syntaxis/syntaxis-cli.toml

Changes Not Applied

Configuration is loaded at startup:

# 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 for basic usage
• See docs/installation.md for installation help
• See TROUBLESHOOTING.md for common issues
• Visit https://doc.syntaxis.dev for online documentation

---

SYNTAXIS v0.1.0 • syntaxis.dev