CLI Reference

Command-line interface documentation

Overview

AI Viewer is a static HTML application served via any HTTP server. The simplest approach uses Python’s built-in server.

Quick Start

# Start server from project root
cd /path/to/2026project
python -m http.server 4100

# Open viewer
open http://localhost:4100/ai-viewer/viewer.html

Server Requirements

The HTTP server must run from the project root (parent of both ai-viewer and pdai) to access all resources:

2026project/          ← Start server here
├── ai-viewer/
│   └── viewer.html
├── pdai/
│   ├── E57/
│   ├── Goldbach/
│   └── ...
└── pdai-documents.json

URL Patterns

Viewer URLs

URL Description
/ai-viewer/viewer.html Home catalog (all documents)
/ai-viewer/viewer.html?doc=pdai/E57 View E57 document
/ai-viewer/viewer.html?doc=pdai/E57&page=10 E57 page 10
/ai-viewer/viewer.html?doc=pdai/E57&mode=agent Agent mode

Document Content URLs

URL Description
/pdai/E57/pages/page_000/page_000.png Page image
/pdai/E57/pages/page_000/page_000.html Page HTML
/pdai/E57/pages/page_000/page_000.xml Page XML
/pdai/E57/pages/page_000/page_000_translation_english.xml Translation
/pdai/E57/manifest.json Document manifest

URL Parameters

Parameter Description Example
doc Document path doc=pdai/E57
page Starting page (0-indexed) page=5
mode View mode mode=agent or mode=document
lang Language lang=english or lang=german

Full example:

http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57&page=10&mode=agent

Port Configuration

Default Port (4100)

python -m http.server 4100

Custom Port

python -m http.server 5100
# Access at http://localhost:5100/ai-viewer/viewer.html

Port Conflicts

# Check what's using a port
lsof -i :4100

# Use different port
python -m http.server 4101

Alternative Servers

Python 3

python -m http.server 4100

Node.js (http-server)

npx http-server -p 4100

nginx

server {
    listen 4100;
    root /path/to/2026project;
    
    location / {
        try_files $uri $uri/ =404;
    }
}

Examples

Development Workflow

# 1. Process document with ai-scholar
ai-scholar process ../pdai/E57/E57.pdf
ai-scholar segment ../pdai/E57
ai-scholar agent ../pdai/E57 translation-english --pages 0-50

# 2. Start server from project root
cd /path/to/2026project
python -m http.server 4100

# 3. View result
open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57"

View Multiple Documents

# Start server once
python -m http.server 4100

# View different documents by changing URL
open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57"
open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/Goldbach"
open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/ActaTominicana1523"

Background Server

# Start in background
python -m http.server 4100 &

# Stop later
kill %1

Troubleshooting

Document Not Found

# Check document exists
ls -la ../pdai/DocumentName/

# Verify page structure
ls ../pdai/DocumentName/pages/page_000/

404 Errors

Ensure server runs from project root:

# Wrong - from ai-viewer
cd ai-viewer
python -m http.server 4100  # ❌ pdai not accessible

# Correct - from project root
cd /path/to/2026project
python -m http.server 4100  # ✓ both accessible

Port Already in Use

# Find what's using the port
lsof -i :4100

# Kill process or use different port
python -m http.server 4101

Permission Denied

# Ports below 1024 require root
python -m http.server 80  # ❌ Permission denied

# Use higher port
python -m http.server 4100  # ✓ Works

Keyboard Shortcuts

Once viewing a document:

Key Action
← → Navigate pages
↑ ↓ Zoom in/out
D Document mode
A Agent mode
R Refresh agent result
F Toggle fullscreen
H Hide navbar

See Also