Merge pull request #1 from YurenHao0426/agent-cli

Headless CLI mode for agents

1 files changed, 102 insertions, 2 deletions

diff --git a/README.md b/README.md
index 3ce3ad1..ad04473 100644
--- a/README.md
+++ b/README.md
@@ -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