syntaxis/docs/install.md

Installation Guide

Complete reference for extracting and installing SYNTAXIS from the bundle.

Overview

This guide covers:

1. Quick overview (3 steps)
2. Prerequisites (system requirements)
3. Installation methods (automatic, manual, NuShell)
4. Verification (checking successful installation)
5. Troubleshooting (common issues)

🚀 Quick Start (4 Steps)

# Step 1: Extract bundle
tar -xzf syntaxis-v0.1.0-*.tar.gz
cd syntaxis-v0.1.0-*

# Step 2: Install binaries
bash install.sh --interactive

# Step 3: Configure settings
bash setup-config.sh --interactive

# Step 4: Verify
syntaxis-cli --version

---

Prerequisites

System Requirements

• Memory: 512 MB minimum (1 GB recommended for full stack)
• Disk Space: 100 MB for binaries + data
• Network: Optional (offline operation supported)

Supported Platforms

Platform	Architecture	Status
Linux (glibc)	x86_64, ARM64	✅ Tested
macOS	Intel (x86_64), Apple Silicon (ARM64)	✅ Tested
Windows	x86_64 (MSVC)	✅ Tested

Required Tools

The bundle is self-contained—no additional tools required!

Optional tools (for advanced setup):

• bash or zsh (for install.sh) - available on all systems
• nu (for install.nu) - install NuShell

---

Installation Methods

Recommended: Two-Step Installation

The cleanest approach: separate install and config steps.

Step 1: Install binaries

# Interactive (prompts for options)
bash install.sh --interactive

# Unattended (uses defaults)
bash install.sh --prefix ~/.local

# Verify before installing
bash install.sh --prefix ~/.local --dry-run

# Custom prefix
bash install.sh --prefix /opt/syntaxis

Step 2: Configure

bash setup-config.sh --interactive

Alternative: NuShell Installer

For NuShell users who prefer the alternative:

# Make sure NuShell is installed first
# See: https://www.nushell.sh/book/installation.html

# Step 1: Install using NuShell
nu install.nu --prefix ~/.local

# Step 2: Configure
bash setup-config.sh --interactive

Advanced: Manual Installation

For maximum control and custom setups:

# Create installation directory
mkdir -p ~/.local/bin

# Copy binaries
cp bin/* ~/.local/bin/

# Make executable
chmod +x ~/.local/bin/syntaxis-*

# Create config directory
mkdir -p ~/.config/syntaxis

# Copy configs
cp configs/*.toml ~/.config/syntaxis/

# Create data directory
mkdir -p ~/.local/share/syntaxis

# Update PATH (one-time)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

---

Step-by-Step Installation

1. Extract Bundle

# Using tar (Linux, macOS)
tar -xzf syntaxis-v0.1.0-*.tar.gz
cd syntaxis-v0.1.0-*

# Using unzip (Windows, macOS)
unzip syntaxis-v0.1.0-*.zip
cd syntaxis-v0.1.0-*

2. Install Binaries

bash install.sh --interactive

This installs the binaries and updates your PATH automatically.

3. Configure Settings

bash setup-config.sh --interactive

This creates configuration files and prompts for customization.

4. Configure Shell

After installation, update your shell configuration to add syntaxis to PATH:

For bash/zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

For fish:

set -Ua fish_user_paths ~/.local/bin

For NuShell:

export PATH="($env.HOME)/.local/bin:($env.PATH)"

5. Verify Installation

# Check all binaries
syntaxis-cli --version
syntaxis-tui --version
syntaxis-api --version

# Should show: syntaxis-* v0.1.0

# List configuration
ls ~/.config/syntaxis/

---

NuShell: Full-Featured Wrappers (Optional)

What is NuShell?

NuShell is a modern shell that provides advanced features for SYNTAXIS wrappers:

• Better config discovery with multiple fallback paths
• Advanced environment variable handling
• Full-featured configuration injection

Do I Need NuShell?

Short Answer: No, SYNTAXIS works without it.

With NuShell (Recommended):

• ✅ Full-featured wrappers
• ✅ Advanced config discovery
• ✅ Best user experience

Without NuShell (Still Works):

• ✅ Simplified auto-config (basic paths only)
• ✅ Still auto-injects config path
• ✅ Good enough for most users

Installing NuShell

The installer will detect if NuShell is installed and prompt you with options:

⚠️  NuShell Not Detected
Continue with simplified wrappers? [Y/n/i]
  Y = Yes, continue (recommended)
  N = No, let me install NuShell first
  i = Show installation guide

Installation Instructions (by OS):

macOS (Homebrew):

brew install nushell

macOS (Cargo):

cargo install nu

Linux (Arch):

pacman -S nushell

Linux (Ubuntu/Debian):

cargo install nu

Linux (Fedora):

dnf install nushell

Windows (WinGet):

winget install nushell

Windows (Cargo):

cargo install nu

Using Wrappers Without NuShell

If you choose to continue without NuShell:

• Wrappers still auto-discover and inject config paths
• Basic config discovery works (~6 paths searched)
• Command execution is normal and transparent

To upgrade later, simply install NuShell:

# Install NuShell (see above for your OS)
# Then re-run the installer
./install.sh

---

Environment Setup

Essential Environment Variables

Set these in your shell rc file:

# Configuration directory
export SYNTAXIS_CONFIG_DIR="$HOME/.config/syntaxis"

# Data directory
export SYNTAXIS_DATA_DIR="$HOME/.local/share/syntaxis"

# Database backend (optional)
export SYNTAXIS_DATABASE="default"  # or "surrealdb"

Optional Configuration

# Logging level
export RUST_LOG="info"  # debug, info, warn, error

# API server settings
export SYNTAXIS_API_PORT=3000
export SYNTAXIS_API_HOST=127.0.0.1

---

Post-Installation Configuration

Interactive Configuration

# Run interactive configuration (done in step 3)
bash setup-config.sh --interactive

Manual Configuration

Default configs are created automatically. Customize them:

# Edit CLI configuration
nano ~/.config/syntaxis/syntaxis-cli.toml

# Edit TUI configuration
nano ~/.config/syntaxis/syntaxis-tui.toml

# Edit API configuration
nano ~/.config/syntaxis/syntaxis-api.toml

See CONFIG.md for all configuration options.

---

Bundle Contents Reference

syntaxis-v0.1.0-<target>/
├── Binaries (ready to run)
│   └── bin/
│       ├── syntaxis-cli       # Command-line interface
│       ├── syntaxis-tui       # Terminal user interface
│       └── syntaxis-api       # REST API server
│
├── Installation Scripts
│   ├── install.sh             # Bash installer (Step 1: Install binaries)
│   ├── install.nu             # NuShell installer (alternative)
│   └── setup-config.sh        # Configuration helper (Step 2: Configure)
│
├── Configurations
│   └── configs/
│       ├── database-default.toml     # SQLite settings
│       ├── database-surrealdb.toml   # SurrealDB settings
│       ├── syntaxis-cli.toml         # CLI config
│       ├── syntaxis-tui.toml         # TUI config
│       └── syntaxis-api.toml         # API config
│
├── Documentation
│   ├── README.md               # Overview (this directory)
│   ├── QUICK_START.md          # 5-minute tutorial
│   ├── docs/installation.md              # Installation (this file)
│   ├── CONFIG.md               # Configuration reference
│   └── TROUBLESHOOTING.md      # Common issues
│
└── Metadata
    ├── manifest.toml           # Bundle inventory
    └── .checksums.toml         # SHA256 checksums

---

Verification

Verify Binaries

# Check all binaries are executable
which syntaxis-cli
which syntaxis-tui
which syntaxis-api

# Test basic commands
syntaxis-cli --help
syntaxis-cli --version

Verify Configuration

# Check config directory
ls -la ~/.config/syntaxis/

# Validate TOML files
cat ~/.config/syntaxis/syntaxis-cli.toml | head -10

Verify Data Directory

# Check data directory exists
ls -la ~/.local/share/syntaxis/

# Create sample database
syntaxis-cli project list

---

Troubleshooting Installation

"Command not found"

# Check if in PATH
echo $PATH | grep .local/bin

# Add to PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

"Permission denied"

# Make binaries executable
chmod +x ~/.local/bin/syntaxis-*

# Verify permissions
ls -l ~/.local/bin/syntaxis-*

Installer script fails

# Run with verbose output
bash install.sh --verbose --prefix ~/.local

# Check if directories exist
mkdir -p ~/.local/bin
mkdir -p ~/.config/syntaxis
mkdir -p ~/.local/share/syntaxis

Configuration not found

# Create missing directory
mkdir -p ~/.config/syntaxis

# Run setup script
bash setup-config.sh

# Copy from bundle
cp configs/*.toml ~/.config/syntaxis/

See TROUBLESHOOTING.md for more help.

---

Uninstallation

To remove SYNTAXIS:

# Remove binaries
rm ~/.local/bin/syntaxis-*

# Remove configuration (optional)
rm -rf ~/.config/syntaxis/

# Remove data (optional)
rm -rf ~/.local/share/syntaxis/

# Clean up PATH (edit ~/.bashrc or equivalent)
# Remove the SYNTAXIS-related export statement

---

Next Steps

1. Quick Start: Read QUICK_START.md (5 minutes)
2. Configure: Read CONFIG.md for all options
3. Create Project: Use syntaxis-cli or syntaxis-tui
4. Run API: Start server with syntaxis-api

---

Getting Help

• Local Issues: Check TROUBLESHOOTING.md
• Configuration: See CONFIG.md
• Quick Examples: See QUICK_START.md
• Online Help: https://doc.syntaxis.dev
• Report Issues: https://github.com/syntaxis/syntaxis/issues

---

SYNTAXIS v0.1.0 • syntaxis.dev