/ 
Webservice-Overleaf-API-0.05
/ overleaf

NAME

overleaf - command-line client for Webservice::Overleaf::API

SYNOPSIS

overleaf [global-options] COMMAND [command-arguments]

overleaf --help
overleaf --version

overleaf project-url PROJECT_ID
overleaf git-url PROJECT_ID

overleaf open-uri URL
overleaf open-uri --engine lualatex --main-document main.tex URL
overleaf open-data paper.tex
overleaf snippet-form paper.tex

overleaf clone PROJECT_ID DIRECTORY
overleaf pull DIRECTORY
overleaf push DIRECTORY
overleaf remote-add DIRECTORY PROJECT_ID [REMOTE]

overleaf --experimental projects
overleaf --experimental bootstrap
overleaf --experimental zip PROJECT_ID
overleaf --experimental compile PROJECT_ID
overleaf --experimental pdf PROJECT_ID
overleaf --experimental output PROJECT_ID output.log

DESCRIPTION

overleaf is the command-line companion to Webservice::Overleaf::API.

It exposes the supported Overleaf import and Git integration surfaces as well as the module's explicitly opt-in experimental browser-session operations.

The program is implemented as a modulino. Loading bin/overleaf from a test or another Perl program does not invoke main() automatically.

The official/supported operations are URL generation, Open in Overleaf import helpers, and the Overleaf Git bridge. Project listing, ZIP download, remote compilation, PDF retrieval, and compile-output retrieval use undocumented Overleaf web-application interfaces and therefore require --experimental.

COMMANDS

project-url PROJECT_ID

Print the normal browser/editor URL for an Overleaf project.

git-url PROJECT_ID

Print the Overleaf Git bridge remote URL for a project.

open-uri URL [URL ...]

Generate an Open in Overleaf URL for one or more remote TeX or ZIP resources.

Relevant options are --engine, --main-document, --visual-editor/--no-visual-editor, and repeatable --name.

open-data FILE

Read FILE and generate an Open in Overleaf data URI.

--mime defaults in the API to application/x-tex. Use an appropriate MIME type when importing other content, such as a ZIP archive.

snippet-form FILE

Read FILE as a TeX snippet and print a complete HTML form that POSTs the snippet to Overleaf. The generated form includes an Open in Overleaf submit button.

clone PROJECT_ID DIRECTORY

Clone the project's official Overleaf Git remote into DIRECTORY.

Authentication is handled by Git itself. The client does not place Git credentials or tokens in the remote URL.

pull DIRECTORY

Run git -C DIRECTORY pull through the API client's Git runner.

push DIRECTORY

Run git -C DIRECTORY push through the API client's Git runner.

remote-add DIRECTORY PROJECT_ID [REMOTE]

Add an Overleaf Git remote to an existing repository.

REMOTE defaults to overleaf. --remote NAME is an alternative to the optional positional REMOTE argument.

bootstrap

Validate the configured browser session and obtain the CSRF state required by experimental web-application calls.

For safety, the CSRF token is not printed. A successful bootstrap prints:

authenticated

Requires --experimental and a browser-session credential.

projects

List active projects as tab-separated records:

PROJECT_ID    NAME    LAST_UPDATED

Archived and trashed projects are omitted by the API client.

Requires --experimental and a browser-session credential.

zip PROJECT_ID

Download the full project ZIP.

The default output filename is PROJECT_ID.zip. Override it with --output.

Requires --experimental and a browser-session credential.

compile PROJECT_ID

Trigger an Overleaf compile and print the resulting status, PDF URL, and reported compile outputs as tab-separated records.

Use --resource-path FILE to request a specific root resource.

Requires --experimental and a browser-session credential.

pdf PROJECT_ID

Compile the project and download the generated PDF.

The default output filename is PROJECT_ID.pdf. Override it with --output.

Use --resource-path FILE to request a specific root resource.

Requires --experimental and a browser-session credential.

output PROJECT_ID PATH

Compile the project and download one named compile artifact, for example:

overleaf --experimental output PROJECT_ID output.log
overleaf --experimental output PROJECT_ID output.bbl
overleaf --experimental output PROJECT_ID output.aux

The default local filename is the basename of PATH. Override it with --output.

Requires --experimental and a browser-session credential.

help

Display the full manual.

OPTIONS

-h, --help

Display the full manual and exit successfully.

-v, --version

Print the command name and the installed Webservice::Overleaf::API version.

--experimental

Enable methods backed by Overleaf's undocumented browser web-application interface.

This option is required for bootstrap, projects, zip, compile, pdf, and output.

--session VALUE

Supply the Overleaf browser-session cookie value directly.

Using OVERLEAF_SESSION or --session-file is preferable because command arguments may be visible to other users on the same machine.

--session-file FILE

Read the Overleaf browser-session cookie value from FILE.

The file should contain only the value of the overleaf_session2 cookie on a single line; do not include overleaf_session2=. A single trailing newline is removed. See "AUTHENTICATION" for the current procedure for creating the file and the approximately five-day session lifetime.

--csrf VALUE

Supply a previously obtained CSRF token. Normally the client bootstraps one from the Overleaf project page when needed.

--base-url URL

Override the Overleaf base URL. The default is:

https://www.overleaf.com

This is useful with self-hosted Overleaf installations.

--git-base-url URL

Override the Git bridge base URL.

For Overleaf Cloud the default is:

https://git.overleaf.com

--cookie-name NAME

Override the browser-session cookie name.

The default is overleaf_session2.

--timeout SECONDS

Set the HTTP timeout.

--engine ENGINE

Set the TeX engine for Open in Overleaf imports.

Supported values are:

latex_dvipdf
pdflatex
xelatex
lualatex

--main-document FILE

Specify the main document for Open in Overleaf imports.

--visual-editor, --no-visual-editor

Request or disable the Overleaf Visual Editor for Open in Overleaf imports.

--name NAME

Specify an imported filename for open-uri or open-data.

The option may be repeated when importing multiple URIs.

--mime TYPE

Set the MIME type used by open-data.

-o FILE, --output FILE

Set the local output filename for zip, pdf, or output.

--resource-path FILE

Request a specific root resource for compile, pdf, or output.

--remote NAME

Set the remote name used by remote-add.

AUTHENTICATION

overleaf has two separate authentication paths because the official Git bridge and the experimental browser-session interface are different Overleaf services.

Git bridge

Git operations use Git's own authentication facilities.

For Overleaf Cloud, create a Git authentication token in the Overleaf account settings under Git Integration. Git uses git as the username and the Overleaf Git token as the password. Store the credential with an appropriate Git credential helper rather than embedding it in a repository URL or command line.

The overleaf client intentionally does not copy, store, or inject the Git token itself.

Experimental browser-session operations

projects, bootstrap, zip, compile, pdf, and output use Overleaf's browser-session authentication and currently require the value of the overleaf_session2 cookie from an already authenticated browser.

For Firefox:

  1. Log into https://www.overleaf.com/ normally.

  2. Press F12, open the Storage tab, then open Cookies and select https://www.overleaf.com.

  3. Find the cookie named overleaf_session2 and copy its Value.

  4. Save only that value in a local file. Do not include the overleaf_session2= prefix.

For Chrome, Edge, and other Chromium-family browsers, the same value is under Developer Tools, Application, Storage, Cookies.

For the current working-directory style:

printf '%s\n' 'PASTE_COOKIE_VALUE_HERE' > ~/.ol-session.txt
chmod 600 ~/.ol-session.txt

The resulting session.out is simply one line containing the cookie value. It is not JSON, not a Netscape cookie file, and not a name=value pair.

Authenticate a command with:

overleaf --experimental --session-file ~/.ol-session.txt projects

For a particular project:

overleaf --experimental --session-file ./session.out \
    compile 672ba784883f09972c460cd6

The same credential may instead be placed in the environment:

export OVERLEAF_SESSION='PASTE_COOKIE_VALUE_HERE'
overleaf --experimental projects

--session VALUE is also supported, but --session-file or OVERLEAF_SESSION is preferable because direct command-line arguments may be visible in process listings and shell history.

How long does the session last?

As of the Overleaf Cookie Policy last modified 5 August 2026, overleaf_session2 has a documented 5-day retention period. In practical terms, treat session.out as a short-lived credential and expect to copy a fresh overleaf_session2 value from the browser about every five days when needed.

The five-day period is not a promise that a particular copied value will remain valid for exactly five days. Logging out, revocation, rotation, security changes, or other server-side invalidation may end the session earlier. If an experimental command begins returning an authentication failure, log into Overleaf in the browser and replace session.out with the current cookie value.

The current Overleaf cookie policy is published at https://www.overleaf.com/legal.

PRACTICAL WALKTHROUGH

This section shows a complete shell workflow, beginning with browser authentication and ending with source inspection, remote compilation, PDF viewing, build-artifact retrieval, and Git interaction.

1. Obtain the browser session

The experimental commands use the same authenticated session as the Overleaf web application. Log into https://www.overleaf.com/ normally.

In Firefox:

  1. Press F12 and open Developer Tools.

  2. Select Storage, then Cookies, then https://www.overleaf.com.

  3. Find overleaf_session2.

  4. Copy only its Value.

In Chrome, Edge, or another Chromium-family browser, open Developer Tools, select Application, then Storage, Cookies, and https://www.overleaf.com.

Save only the cookie value in a protected file:

printf '%s\n' 'PASTE_COOKIE_VALUE_HERE' > ~/.ol-session.txt
chmod 600 ~/.ol-session.txt

Do not write:

overleaf_session2=PASTE_COOKIE_VALUE_HERE

The file is just one line containing the cookie value.

For the rest of this walkthrough:

SESSION=~/.ol-session.txt

Overleaf currently documents a five-day retention period for overleaf_session2. Treat that as an approximate lifetime: logout, revocation, rotation, or server-side invalidation can end a session earlier.

2. Verify the session

Run:

overleaf --experimental \
    --session-file "$SESSION" \
    bootstrap

Success looks like:

authenticated

If this fails after previously working, obtain a fresh overleaf_session2 value from the browser and replace the contents of ~/.ol-session.txt.

3. List projects and choose an ID

List active projects:

overleaf --experimental \
    --session-file "$SESSION" \
    projects

The output is tab-separated:

PROJECT_ID    PROJECT NAME    LAST_UPDATED

Choose one project and keep its ID in a shell variable:

ID=0123456789abcdef

You can verify the normal browser URL and Git URL without using the session:

overleaf project-url "$ID"
overleaf git-url "$ID"

4. Download and inspect the source project

To inspect the source tree, download the full project ZIP:

overleaf --experimental \
    --session-file "$SESSION" \
    --output project.zip \
    zip "$ID"

The command prints the saved filename:

project.zip

List everything in the archive:

unzip -l project.zip

Find the TeX source files:

unzip -l project.zip | grep -Ei '\.tex$'

For a larger project this might show a root document and many included files:

user_guide.tex
preface.tex
setup.tex
appendix/basic_commands.tex
appendix/memory_map.tex

To work with the complete source tree locally:

mkdir project-src
cd project-src
unzip ../project.zip

Then:

find . -type f -name '*.tex' -print

zip and compile answer different questions. zip retrieves project source files. compile reports generated build artifacts.

5. Compile the project

Compile using Overleaf's configured root document:

overleaf --experimental \
    --session-file "$SESSION" \
    compile "$ID"

The first lines look approximately like:

status  success
pdf     https://www.overleaf.com/project/.../output/output.pdf?...

They are followed by generated build artifacts such as:

output  output.aux      aux      ...
output  output.bbl      bbl      ...
output  output.chktex   chktex   ...
output  output.log      log      ...
output  output.pdf      pdf      ...

Packages such as minted may generate many additional entries under paths such as _minted-output/. This is normal. These are build outputs, not source .tex files.

6. Discover the configured root TeX document

If you do not know which .tex file Overleaf is compiling, retrieve output.log:

overleaf --experimental \
    --session-file "$SESSION" \
    --output output.log \
    output "$ID" output.log

The TeX log normally begins with a line similar to:

**user_guide.tex

A useful shell command is:

grep -m1 '^\*\*[^*]' output.log

The [^*] prevents later diagnostic lines beginning with several asterisks from being mistaken for the root-document line.

Save the result as appropriate, for example:

ROOT_TEX=user_guide.tex

7. Compile an explicit root document

Once the root filename is known:

overleaf --experimental \
    --session-file "$SESSION" \
    --resource-path "$ROOT_TEX" \
    compile "$ID"

This is useful when a project contains multiple independently compilable TeX documents or when scripting a publication workflow.

8. Download the PDF

Compile and save the resulting PDF:

overleaf --experimental \
    --session-file "$SESSION" \
    --resource-path "$ROOT_TEX" \
    --output document.pdf \
    pdf "$ID"

Check it:

file document.pdf
ls -lh document.pdf

On a Linux desktop, open it with the system default viewer:

xdg-open document.pdf >/dev/null 2>&1 &

On Windows from MSYS2 or Git Bash:

start document.pdf

If Windows path conversion is needed explicitly:

cmd.exe /c start "" "$(cygpath -w document.pdf)"

9. Retrieve build artifacts

The compile result exposes useful LaTeX diagnostics. For example:

overleaf --experimental \
    --session-file "$SESSION" \
    --output document.log \
    output "$ID" output.log

overleaf --experimental \
    --session-file "$SESSION" \
    --output document.bbl \
    output "$ID" output.bbl

overleaf --experimental \
    --session-file "$SESSION" \
    --output document.chktex \
    output "$ID" output.chktex

Inspect them using ordinary shell tools:

tail -100 document.log
cat document.bbl
cat document.chktex

Only artifacts actually reported by compile can be downloaded with output.

10. Use the official Git bridge

The Git bridge does not use ~/.ol-session.txt. It uses Overleaf's Git integration and token-based Git authentication, with credentials handled by Git.

Print the remote URL:

overleaf git-url "$ID"

Clone the Overleaf project:

overleaf clone "$ID" my-paper

Inspect the clone:

cd my-paper
git status
git remote -v
git log --oneline -10

Pull changes made in the Overleaf editor:

cd ..
overleaf pull my-paper

After editing locally, commit normally:

cd my-paper
git add .
git commit -m 'update paper'
cd ..

For a clone whose current branch already tracks the Overleaf remote:

overleaf push my-paper

The push command changes the remote Overleaf project, so verify git status and the commits you intend to publish before using it.

11. Add Overleaf to an existing Git repository

Instead of cloning, an existing local repository can gain an Overleaf remote:

cd existing-paper
overleaf remote-add . "$ID" overleaf
git remote -v

Overleaf's Git bridge has important differences from a general-purpose Git server. It exposes one linear project history and the remote branch is currently named master. For an unrelated existing repository, Overleaf's documented initialization workflow includes reconciling the histories before the first push. A typical explicit push after the repository has been prepared is:

git push overleaf master --set-upstream

A local branch with another name can be mapped to Overleaf's branch:

git push overleaf my-branch:master

12. A compact repeatable workflow

After the initial setup, an ordinary read/compile/download cycle can be as small as:

SESSION=~/.ol-session.txt
ID=0123456789abcdef

overleaf --experimental --session-file "$SESSION" \
    --output project.zip zip "$ID"

overleaf --experimental --session-file "$SESSION" \
    compile "$ID"

overleaf --experimental --session-file "$SESSION" \
    --output output.log output "$ID" output.log

overleaf --experimental --session-file "$SESSION" \
    --output document.pdf pdf "$ID"

start document.pdf

Use xdg-open document.pdf instead of start on Linux.

ENVIRONMENT

OVERLEAF_SESSION

Browser-session cookie value used by experimental web-application operations when no explicit session is supplied.

EXAMPLES

Create a protected browser-session file after copying the current overleaf_session2 value from browser Developer Tools:

printf '%s\n' 'PASTE_COOKIE_VALUE_HERE' > ~/.ol-session.txt
chmod 600 ~/.ol-session.txt

List projects using that file:

overleaf --experimental --session-file ~/.ol-session.txt projects

List projects using the environment instead:

OVERLEAF_SESSION='...' overleaf --experimental projects

Clone a paper through the official Git bridge:

overleaf clone 0123456789abcdef paper

Add an Overleaf remote to an existing local repository:

overleaf remote-add . 0123456789abcdef overleaf

Generate an Open in Overleaf URL:

overleaf open-uri \
    --engine lualatex \
    --main-document AUTHOR-paper.tex \
    https://example.org/paper.zip

Compile a specific root document:

OVERLEAF_SESSION='...' \
    overleaf --experimental \
    --resource-path AUTHOR-paper.tex \
    compile 0123456789abcdef

Compile and retrieve the resulting PDF:

OVERLEAF_SESSION='...' \
    overleaf --experimental \
    --resource-path AUTHOR-paper.tex \
    --output AUTHOR-paper.pdf \
    pdf 0123456789abcdef

Retrieve the compilation log:

OVERLEAF_SESSION='...' \
    overleaf --experimental \
    --output AUTHOR-paper.log \
    output 0123456789abcdef output.log

EXIT STATUS

0 indicates success.

1 indicates an operational error, including invalid API arguments, authentication failures, HTTP failures, Git failures, and file I/O failures.

2 indicates command-line usage failure, such as an unknown command.

SECURITY

OVERLEAF_SESSION is an authentication credential. Treat it like a password. Do not commit it, log it, include it in bug reports, or expose it in shell history.

The --session option is less private than OVERLEAF_SESSION or --session-file because command-line arguments may be visible in process listings.

Git authentication tokens are intentionally left to Git's credential handling and are not added to Git URLs by this program.

IMPLEMENTATION

Command-line options are parsed with Getopt2h2o from Util::H2O::More. Commands are routed with Dispatch::Fu. The executable is a modulino whose package is local::bin::overleaf.

AUTHOR

Brett Estrade <oodler@cpan.org>

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.