diff options
| -rw-r--r-- | README.md | 104 | ||||
| -rw-r--r-- | package.json | 3 | ||||
| -rw-r--r-- | tsconfig.json | 3 |
3 files changed, 107 insertions, 3 deletions
@@ -94,6 +94,105 @@ Claude: [calls get_comments] I see 3 comments... No configuration needed — LatteX sets everything up automatically when you open a project. +## Headless / Agent Mode (CLI) + +`lattex-cli` is a headless CLI for working with Overleaf projects from a server with no display. It is designed for AI agents — short output, `--json` mode on every command, meaningful exit codes, errors on stderr. + +### Install + +```bash +# From the repo root: +npm run build:cli +# The CLI is at out/cli/lattex-cli.mjs — run with Node 18+: +node out/cli/lattex-cli.mjs --help +# Or create an alias: +alias lattex-cli='node /path/to/lattex/out/cli/lattex-cli.mjs' +``` + +### Authentication + +The CLI needs an Overleaf session cookie. Three ways to provide it: + +```bash +# 1. Direct cookie string (from browser dev tools → Application → Cookies) +lattex-cli auth --cookie "overleaf_session2=s%3A..." + +# 2. From environment variable +export LATTEX_COOKIE="overleaf_session2=s%3A..." +lattex-cli projects + +# 3. From a running Chromium with remote debugging (e.g. --remote-debugging-port=18801) +lattex-cli auth --from-cdp http://127.0.0.1:18801 +``` + +The cookie is stored at `~/.config/lattex/auth.json` with mode 600. Cookie values are never printed. + +### Commands + +```bash +# List projects +lattex-cli projects [--json] + +# Clone a project to a local directory +lattex-cli clone <project-id-or-name> <dir> + +# Pull latest changes from Overleaf +lattex-cli pull <dir> + +# Show local changes +lattex-cli status <dir> + +# Push local changes to Overleaf +lattex-cli push <dir> [--dry-run] [--delete] [--force] +# --dry-run Show what would be pushed without pushing +# --delete Allow deleting remote files that were deleted locally +# --force Push even if remote has changed since last pull + +# Compile on Overleaf server and download PDF +lattex-cli compile <dir> [--out output.pdf] +``` + +All commands accept `--json` for machine-readable output. + +### Exit Codes + +| Code | Meaning | +|------|---------| +| 0 | Success | +| 1 | General error | +| 2 | Authentication error | +| 3 | Conflict (remote changed) | +| 64 | Usage error | + +### Example: Template Migration (AAAI → ICLR) + +```bash +lattex-cli auth --cookie "$OVERLEAF_COOKIE" +lattex-cli clone "My AAAI Paper" /tmp/paper +cd /tmp/paper +# ... edit files to change template ... +lattex-cli push . --dry-run # preview changes +lattex-cli push . # upload +lattex-cli compile . --out paper.pdf # compile and download PDF +``` + +### Testing with a Live Session + +The CLI requires a valid Overleaf session for all commands except `--help` and `status`. To test live: + +```bash +# 1. Get your Overleaf cookie (browser → dev tools → Application → Cookies → overleaf_session2) +# 2. Auth +lattex-cli auth --cookie "overleaf_session2=..." +# 3. List projects to verify +lattex-cli projects --json +# 4. Clone, edit, push, compile +lattex-cli clone <project-id> /tmp/test-project +echo "% test" >> /tmp/test-project/main.tex +lattex-cli status /tmp/test-project +lattex-cli push /tmp/test-project --dry-run +``` + ## Development ```bash @@ -104,8 +203,9 @@ npm run dev ### Build ```bash -npm run build -npx electron-builder --mac dmg +npm run build # Electron app + MCP server +npm run build:cli # Headless CLI (out/cli/lattex-cli.mjs) +npx electron-builder --mac dmg # macOS installer ``` ## License diff --git a/package.json b/package.json index e645d94..d736062 100644 --- a/package.json +++ b/package.json @@ -8,6 +8,9 @@ "scripts": { "dev": "electron-vite dev", "build": "electron-vite build && npx esbuild src/mcp/lattex.mjs --bundle --platform=node --format=esm --outfile=out/mcp/lattex.mjs", + "build:cli": "npx esbuild src/cli/main.ts --bundle --platform=node --format=esm --target=node18 --outfile=out/cli/lattex-cli.mjs --external:ws --banner:js='#!/usr/bin/env node'", + "typecheck:cli": "npx tsc --project tsconfig.cli.json --noEmit", + "test:cli": "node --experimental-vm-modules out/cli/test.mjs", "preview": "electron-vite preview", "postinstall": "electron-builder install-app-deps", "pack": "electron-builder --dir", diff --git a/tsconfig.json b/tsconfig.json index 155ebaa..1ab89d5 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -2,6 +2,7 @@ "files": [], "references": [ { "path": "./tsconfig.node.json" }, - { "path": "./tsconfig.web.json" } + { "path": "./tsconfig.web.json" }, + { "path": "./tsconfig.cli.json" } ] } |