v0.3.1: fix clsiserverid 404 (#22), subfolder uploads, add --verbose (#21)

- fix(client): append ?clsiserverid=<id> to all build-output URLs so
  olcli pdf / olcli output <type> work again. Overleaf's CDN now
  requires the hint or returns 404. Closes #22.
- fix(upload): preserve the relative path (figures/fig01.png) instead
  of basename-stripping it; lazy-load and cache the folder tree inside
  OverleafClient.uploadFile so files land in the correct subfolder.
- fix(sync): subfolder files in the sync upload pass now also land in
  the right folder via the same self-healing path in uploadFile.
- feat(cli): global --verbose flag prints every HTTP request, status,
  and (on errors) a response-body snippet to stderr. Closes #21.
- docs(README): new Global options section; cross-link from Sync and
  Self-hosted Overleaf sections.
- chore: bump to 0.3.1, update CHANGELOG.

Author: aloth

CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.1] - 2026-05-18
+
+### Fixed
+- **`olcli pdf` / `olcli output <type>` returned `Download failed: 404`** (#22) — Overleaf's CDN now requires `?clsiserverid=<id>` on every build-output download. We were stripping that hint. The compile response's `clsiServerId` field is now appended to all output URLs (`pdf`, `bbl`, `log`, `aux`, …).
+- **`olcli upload figures/fig01.png` placed the file in project root** instead of inside `figures/`. The CLI previously called `basename()` on the path and never resolved the folder tree. Now the relative path is preserved and the folder tree is loaded (and cached) on demand. Subfolders are auto-created if missing.
+- **`olcli sync` upload pass** also dropped subfolder information when pushing local-newer files. Same fix as above (`uploadFile` now self-resolves the folder tree when the caller doesn't pass one).
+
+### Added
+- **Global `--verbose` flag** (#21) — prints every HTTP request, status, content-type, and (on non-2xx) a 200-char snippet of the response body to stderr. Use as `olcli --verbose pdf` or `olcli pdf --verbose` for troubleshooting failed compiles, uploads, or auth.
+
+### Internal
+- New `OverleafClient.getOrLoadFolderTree(projectId)` / `invalidateFolderTree(projectId)` helpers with per-project caching, so callers no longer have to plumb a `folderTree` argument through every code path.
+
 ## [0.3.0] - 2026-04-27
 
 ### ⚠ Behavior change

README.md

@@ -178,6 +178,25 @@ All commands auto-detect the project when run from a synced directory (contains
 | `olcli config set-cookie-name <name>` | Set the session cookie name |
 | `olcli check` | Show config paths and credential sources |
 
+### Global options
+
+These flags work with **every** command and may be placed before or after the command name:
+
+| Flag | Description |
+|------|-------------|
+| `--verbose` | Print every HTTP request, status, content-type, and (on errors) a response-body snippet to stderr. Useful for debugging failed compiles, 404s on `pdf`/`output`, auth issues, or unexpected upload behavior. |
+| `--base-url <url>` | Override the Overleaf instance base URL (also `OVERLEAF_BASE_URL` env var or `olcli config set-url`). |
+| `--cookie-name <name>` | Override the session cookie name (default `overleaf_session2`; older instances use `overleaf.sid`). |
+
+Examples:
+
+```bash
+olcli --verbose pdf                    # see every request the compile makes
+olcli pdf --verbose                    # same thing, flag after command
+olcli --verbose sync                   # debug a sync that's misbehaving
+olcli --verbose upload figures/a.png   # confirm the file is placed in figures/
+```
+
 ## Use Cases
 
 ### Local Editing with Overleaf Compilation
@@ -266,7 +285,7 @@ olcli output --list
 - Pushes local changes to remote
 - **Propagates local deletions to the remote** — if you delete a file locally, it's deleted on Overleaf on the next sync. Use `--no-delete` to opt out.
 - Filters out LaTeX build artifacts and OS noise
-- Use `--verbose` to see detailed file operations
+- Use `--verbose` to see detailed file operations (see [Global options](#global-options))
 - Use `--dry-run` to preview without applying
 
 #### How deletion propagation works
@@ -337,14 +356,14 @@ s%3AyourSessionCookieValue...
 
 ### Self-hosted Overleaf / ShareLaTeX
 
-You can point `olcli` at a self-hosted instance and override the session cookie name.
+You can point `olcli` at a self-hosted instance and override the session cookie name. Both flags are documented under [Global options](#global-options) and can be combined with any command.
 
 ```bash
 olcli --base-url https://latex.example.org list
 olcli --base-url https://latex.example.org --cookie-name overleaf.sid whoami
 ```
 
-Persist these settings in `olcli` config:
+Persist these settings in `olcli` config so you don't have to repeat them:
 
 ```bash
 olcli config set-url https://latex.example.org

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aloth/olcli",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Command-line interface for Overleaf — Sync, manage, and compile LaTeX projects from your terminal",
   "type": "module",
   "bin": {

src/cli.ts

@@ -46,7 +46,8 @@ program
   .description('Overleaf CLI - interact with Overleaf projects from the command line')
   .version(VERSION)
   .option('--base-url <url>', 'Overleaf instance base URL (overrides OVERLEAF_BASE_URL and config)')
-  .option('--cookie-name <name>', 'Session cookie name (default: overleaf_session2, use overleaf.sid for older instances)');
+  .option('--cookie-name <name>', 'Session cookie name (default: overleaf_session2, use overleaf.sid for older instances)')
+  .option('--verbose', 'Print every HTTP request, status, and error response body to stderr');
 
 /**
  * Helper to get authenticated client
@@ -62,7 +63,9 @@ async function getClient(cookieOpt?: string, baseUrlOpt?: string): Promise<Overl
   }
   const baseUrl = baseUrlOpt || (program.opts().baseUrl as string | undefined) || getBaseUrl();
   const cookieName = (program.opts().cookieName as string | undefined) || getSessionCookieName();
-  return OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
+  const client = await OverleafClient.fromSessionCookie(cookie, baseUrl, cookieName);
+  if (program.opts().verbose) client.setVerbose(true);
+  return client;
 }
 
 /**
@@ -454,7 +457,11 @@ program
       }
 
       const content = readFileSync(file);
-      const fileName = basename(file);
+      // Preserve the relative path (e.g. 'figures/fig01.png') so the file lands
+      // in the correct subfolder, not in project root. uploadFile() will
+      // lazy-resolve the folder tree when no folderId/tree is supplied.
+      // Normalize: strip leading './' and any leading slashes.
+      const fileName = file.replace(/^(\.\/)+/, '').replace(/^\/+/, '');
 
       // Pass folder ID or null for root folder (client will compute it)
       const folderId = options.folder || null;

src/client.ts

@@ -64,13 +64,44 @@ export class OverleafClient {
   private cookies: Record<string, string>;
   private csrf: string;
   private baseUrl: string;
+  private verbose: boolean = false;
+  // Cache per-project folder trees so repeated uploads in sync/upload calls
+  // don't re-fetch the tree via Socket.IO on every file.
+  private folderTreeCache: Map<string, Record<string, string>> = new Map();
 
   constructor(credentials: Credentials) {
     this.cookies = credentials.cookies;
     this.csrf = credentials.csrf;
     this.baseUrl = credentials.baseUrl || DEFAULT_BASE_URL;
   }
 
+  /** Enable or disable verbose request/response logging to stderr. */
+  setVerbose(v: boolean): void {
+    this.verbose = v;
+  }
+
+  /**
+   * Resolve (and cache) the folder tree for a project. Falls back to a
+   * minimal tree containing only the root folder when the Socket.IO probe
+   * fails (e.g. self-hosted Overleaf without that endpoint).
+   */
+  async getOrLoadFolderTree(projectId: string): Promise<Record<string, string>> {
+    const cached = this.folderTreeCache.get(projectId);
+    if (cached) return cached;
+    let tree = await this.getFolderTreeFromSocket(projectId);
+    if (!tree) {
+      const rootId = await this.getRootFolderId(projectId);
+      tree = { '': rootId };
+    }
+    this.folderTreeCache.set(projectId, tree);
+    return tree;
+  }
+
+  /** Drop the cached folder tree for a project (e.g. after rename/delete). */
+  invalidateFolderTree(projectId: string): void {
+    this.folderTreeCache.delete(projectId);
+  }
+
   private projectUrl(): string {
     return `${this.baseUrl}/project`;
   }
@@ -197,6 +228,13 @@ export class OverleafClient {
     }
   }
 
+  private logVerbose(...args: any[]): void {
+    if (this.verbose) {
+      // eslint-disable-next-line no-console
+      console.error('[olcli]', ...args);
+    }
+  }
+
   private async httpRequest(url: string, options: {
     method?: string;
     headers?: Record<string, string>;
@@ -237,6 +275,7 @@ export class OverleafClient {
           const resHeaders = res.headers as Record<string, string | string[]>;
 
           if (status >= 300 && status < 400 && res.headers.location && redirectsLeft > 0) {
+            this.logVerbose(`${method} ${reqUrl} -> ${status} redirect -> ${res.headers.location}`);
             const redirectUrl = new URL(res.headers.location, reqUrl).toString();
             res.resume();
             doRequest(redirectUrl, redirectsLeft - 1).then(resolve, reject);
@@ -254,10 +293,21 @@ export class OverleafClient {
               try {
                 body = JSON.parse(buffer.toString('utf-8'));
               } catch (e) {
+                this.logVerbose(`${method} ${reqUrl} -> ${status} (invalid JSON, ${buffer.length} bytes)`);
                 return reject(new Error(`Failed to parse JSON response from ${reqUrl}`));
               }
             }
-            resolve({ status, ok: status >= 200 && status < 300, headers: resHeaders, body });
+            const ok = status >= 200 && status < 300;
+            if (this.verbose) {
+              const ct = (resHeaders['content-type'] || '') as string;
+              let snippet = '';
+              if (!ok) {
+                const text = expect === 'buffer' ? '' : (typeof body === 'string' ? body : JSON.stringify(body));
+                snippet = text ? ` body=${text.slice(0, 200).replace(/\s+/g, ' ')}` : '';
+              }
+              this.logVerbose(`${method} ${reqUrl} -> ${status} (${buffer.length}B ${ct})${snippet}`);
+            }
+            resolve({ status, ok, headers: resHeaders, body });
           });
           res.on('error', reject);
         });
@@ -584,8 +634,11 @@ export class OverleafClient {
       throw new Error('No PDF output found');
     }
 
+    // Overleaf's CDN requires ?clsiserverid=<id> for build-output downloads.
+    // Without it the build URL 404s. See: https://github.com/aloth/olcli/issues/22
+    const qs = data.clsiServerId ? `?clsiserverid=${encodeURIComponent(data.clsiServerId)}` : '';
     return {
-      pdfUrl: `${this.baseUrl}${pdfFile.url}`,
+      pdfUrl: `${this.baseUrl}${pdfFile.url}${qs}`,
       logs: data.compileGroup ? [`Compile group: ${data.compileGroup}`] : []
     };
   }
@@ -1071,11 +1124,15 @@ export class OverleafClient {
     // Extract just the filename without path
     const baseName = fileName.split('/').pop() || fileName;
 
-    // Resolve target folder: if fileName has a directory part and we have a folderTree, use it
+    // Resolve target folder: if fileName has a directory part, place the file there.
+    // Lazy-load + cache the folder tree when caller didn't supply one, so external
+    // callers (and our own `upload`/`sync` paths) don't silently dump files into root.
+    // See: https://github.com/aloth/olcli/issues/22 follow-up + 0.3.1 upload-fix.
     const dirPart = fileName.includes('/') ? fileName.split('/').slice(0, -1).join('/') : '';
     let targetFolderId: string;
-    if (dirPart && folderTree) {
-      targetFolderId = await this.resolveFolderId(projectId, folderTree, dirPart);
+    if (dirPart) {
+      const tree = folderTree || await this.getOrLoadFolderTree(projectId);
+      targetFolderId = await this.resolveFolderId(projectId, tree, dirPart);
     } else {
       targetFolderId = folderId || await this.getRootFolderId(projectId);
     }
@@ -1406,13 +1463,16 @@ export class OverleafClient {
     const data = response.body as any;
     const pdfFile = data.outputFiles?.find((f: any) => f.type === 'pdf');
 
+    // Overleaf's CDN requires ?clsiserverid=<id> for build-output downloads.
+    // Without it every output (pdf/log/bbl/...) 404s. See issue #22.
+    const qs = data.clsiServerId ? `?clsiserverid=${encodeURIComponent(data.clsiServerId)}` : '';
     return {
       status: data.status,
-      pdfUrl: pdfFile ? `${this.baseUrl}${pdfFile.url}` : undefined,
+      pdfUrl: pdfFile ? `${this.baseUrl}${pdfFile.url}${qs}` : undefined,
       outputFiles: (data.outputFiles || []).map((f: any) => ({
         path: f.path,
         type: f.type,
-        url: `${this.baseUrl}${f.url}`
+        url: `${this.baseUrl}${f.url}${qs}`
       }))
     };
   }