# Quick Start Guide
**Purpose**: Get started with ix code search in under 10 minutes
**Last Verified**: 2026-05-16
**Verification Command**: `./scripts/verify-docs.sh`
---
## Table of Contents
1. [CLI Quick Start (2 minutes)](#cli-quick-start)
2. [Daemon Quick Start (5 minutes)](#daemon-quick-start)
3. [Socket API Quick Start (3 minutes)](#socket-api-quick-start)
4. [Next Steps](#next-steps)
---
## CLI Quick Start (2 minutes)
### Step 1: Install (30 seconds)
```bash
# Install from crates.io
cargo install moeix
# Expected output:
# Finished release [optimized] target(s) in 45s
# Installed binary `ix`
```
**Source**: `Cargo.toml:1-10`
### Step 2: Build Index (30 seconds)
```bash
cd /path/to/your/repo
ix --build
# Expected output:
# ix: building index for /path/to/your/repo...
# ix: 1234 files, 56789 trigrams in 2.3s
```
**Source**: `src/bin/ix.rs:280-310`
### Step 3: Search (30 seconds)
```bash
# Literal search
ix "fn main"
# Expected output:
# src/main.rs:5:fn main() {
# src/lib.rs:10:pub fn main() -> Result<()> {
# Regex search
ix --regex "fn\s+\w+_handler"
# Expected output:
# src/handlers.rs:42:fn handle_request() {
# src/handlers.rs:58:fn handle_response() {
```
**Source**: `src/bin/ix.rs:320-420`
### Step 4: Verify (30 seconds)
```bash
# Check version
ix --version
# Expected: ix 0.6.3
# Check help
ix --help
# Expected: Full usage information
```
**✅ CLI is working if you see search results!**
---
## Daemon Quick Start (5 minutes)
### Prerequisites
- Rust 1.85+ installed
- `cargo` in PATH
- A repository to watch
### Step 1: Build Daemon (2 minutes)
```bash
cd /workspace/ix
cargo build --release --features notify
# Expected output:
# Finished release [optimized] target(s) in 45s
```
**Source**: `Cargo.toml:85-95`
### Step 2: Start Daemon (1 minute)
```bash
# Start watching a directory
./target/release/ixd /path/to/repo
# Expected output:
# ixd: watching /path/to/repo...
# ixd: initial build complete (1234 files, 56789 trigrams)
# ixd: socket at /run/user/1000/ixd/a1b2c3d4e5f67890.sock
```
**Source**: `src/lib/daemon.rs:54-120`
### Step 3: Verify Daemon (1 minute)
```bash
# Check daemon is running
# Expected: ixd process visible
# Check socket exists
ls -la $XDG_RUNTIME_DIR/ixd/*.sock
# Expected: socket file present
# Query status
echo '{"t":"status_query"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/ixd/*.sock
# Expected: {"pid":12345,"status":"idle","files":1234,"daemon_status":{"state":"idle"}}
```
**Source**: `src/lib/daemon_sock.rs:669-700`
### Step 4: Test Live Indexing (1 minute)
```bash
# Modify a file
echo "// test comment" >> /path/to/repo/src/main.rs
# Watch daemon output (in the terminal where ixd is running)
# Expected: "ixd: 1 files changed, updating index..."
# Query status again
echo '{"t":"status_query"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/ixd/*.sock
# Expected: files count should be same or +1
```
**✅ Daemon is working if status query responds!**
---
## Socket API Quick Start (3 minutes)
### Step 1: Connect (1 minute)
**Python Example:**
```python
import socket
import json
import os
import xxhash
def get_socket_path(root):
"""Get daemon socket path for given root directory."""
canonical = str(Path(root).resolve())
hash_hex = xxhash.xxh64(canonical).hexdigest()[:16]
# Try paths in order
paths = [
f"{os.environ.get('XDG_RUNTIME_DIR', f'/run/user/{os.getuid()}')}/ixd/{hash_hex}.sock",
f"{os.path.expanduser('~')}/.local/run/ixd/{hash_hex}.sock",
f"/tmp/ixd-{os.getuid()}-{hash_hex}.sock"
]
for path in paths:
if os.path.exists(path):
return path
raise FileNotFoundError("Daemon socket not found")
# Connect to daemon
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect(get_socket_path("/path/to/repo"))
print("Connected to daemon!")
```
**Source**: `src/lib/daemon_sock.rs:284-305`
### Step 2: Query Status (1 minute)
```python
# Send status query
query = {"t": "status_query", "id": 1}
sock.sendall((json.dumps(query) + "\n").encode())
# Receive response
response = sock.recv(4096).decode()
print(json.loads(response))
# Expected: {"t":"status","pid":12345,"status":"idle","files":1234,...}
```
**Source**: `src/lib/daemon_sock.rs:560-580`
### Step 3: Search (1 minute)
```python
# Send search query
query = {
"t": "search_query",
"id": 2,
"pattern": "TODO",
"is_regex": False,
"max_results": 5
}
sock.sendall((json.dumps(query) + "\n").encode())
# Receive results
response = sock.recv(8192).decode()
data = json.loads(response)
print(f"Found {len(data.get('matches', []))} matches")
# Expected: {"t":"search_results","id":2,"matches":[...],"stats":{...}}
```
**Source**: `src/lib/daemon_sock.rs:600-640`
**✅ Socket API is working if you get search results!**
---
## Next Steps
### For CLI Users
- [ ] Read `README.md` for advanced search options
- [ ] Learn about regex patterns (`ix --regex`)
- [ ] Explore context options (`ix -C 3`)
### For Daemon Users
- [ ] Read `DAEMON-RUNBOOK.md` for operational procedures
- [ ] Configure systemd service (if on Linux)
- [ ] Set up log rotation
### For API Developers
- [ ] Read `SOCKET-API.md` for complete API reference
- [ ] Implement shutdown handling
- [ ] Add reconnection logic
### For All Users
- [ ] Join community (if applicable)
- [ ] Report issues on GitHub
- [ ] Contribute to documentation
---
## Troubleshooting
### "Command not found: ix"
**Fix**: Ensure `~/.cargo/bin` is in PATH
```bash
export PATH="$HOME/.cargo/bin:$PATH"
```
### "Daemon won't start"
**Check**:
1. Is port already in use? `lsof -i :<port>`
2. Is another instance running? `pgrep -f ixd`
3. Check logs: `journalctl -u ixd` or console output
### "Socket not found"
**Fix**:
1. Verify daemon is running: `ps aux | grep ixd`
2. Check socket directory: `ls -la $XDG_RUNTIME_DIR/ixd/`
3. Restart daemon if needed
### "Index outdated"
**Fix**: Force rebuild
```bash
ix --fresh "pattern"
```
---
## Verification Checklist
Run these to verify your installation:
```bash
# CLI verification
ix --version # Should show version
ix --build # Should build index
ix "test" # Should find matches
# Daemon verification
echo '{"t":"status_query"}' | socat - UNIX-CONNECT:$XDG_RUNTIME_DIR/ixd/*.sock
# API verification (Python)
python3 -c "
import socket, json
sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
sock.connect('YOUR_SOCKET_PATH')
sock.send(b'{\"t\":\"status_query\",\"id\":1}\n')
print(sock.recv(1024).decode())
"
```
**Expected**: All commands complete successfully with expected output.
---
## See Also
- `README.md` — Main project documentation
- `SOCKET-API.md` — Complete API reference
- `DAEMON-RUNBOOK.md` — Operational procedures
- `CONTRIBUTING.md` — How to contribute