NAME

Webservice::Overleaf::API - Perl client helpers for Overleaf import, Git, and experimental project operations

SYNOPSIS

use Webservice::Overleaf::API;

my $ol = Webservice::Overleaf::API->new;

# Official Open in Overleaf interface
my $url = $ol->open_uri(
    uri           => 'https://example.org/paper.zip',
    engine        => 'lualatex',
    main_document => 'main.tex',
);

# Official Git bridge
say $ol->git_url('0123456789abcdef');
$ol->git_clone('0123456789abcdef', 'paper');

# Undocumented web application interface -- opt in explicitly.
my $web = Webservice::Overleaf::API->new(
    experimental => 1,
    session      => $ENV{OVERLEAF_SESSION},
);

for my $project ($web->projects->all) {
    say $project->name;
}

my $compile = $web->compile(
    '0123456789abcdef',
    resource_path => 'main.tex',
);
$web->download_pdf('0123456789abcdef', compile => $compile, to => 'paper.pdf');

DESCRIPTION

This distribution deliberately separates supported Overleaf integration surfaces from browser-session interfaces that Overleaf does not document as a public API.

The supported side covers the Open in Overleaf import interface and the Overleaf Git bridge. The experimental side uses the same project HTML and compile/download endpoints used by the web application. Those endpoints may change without notice and therefore require experimental => 1.

Dispatch::Fu is used for both public operation dispatch and HTTP response classification. Util::H2O::More is used for compact construction and for objectifying returned project and compile data.

CONSTRUCTOR

new

my $ol = Webservice::Overleaf::API->new(
    base_url     => 'https://www.overleaf.com',
    git_base_url => 'https://git.overleaf.com',
    experimental => 0,
    session      => $ENV{OVERLEAF_SESSION},
    cookie_name  => 'overleaf_session2',
    ua           => $http_tiny_compatible_object,
    git_runner   => sub { ... },
);

ua and git_runner are injectable specifically so callers and the test suite can isolate all network and process execution.

OFFICIAL OVERLEAF INTERFACES

open_uri

Builds an Open in Overleaf URL. Accepts uri or uris, optional name or names, and the documented engine, main_document, and visual_editor features.

open_data

Base64-encodes content into a data URI and returns an Open in Overleaf URL. The default MIME type is application/x-tex; use application/zip for a ZIP project.

open_snippet_form

Returns an object describing a POST form to /docs with a raw snip field. This is useful when embedding an Open in Overleaf button in an application.

project_url

Returns the normal browser/editor URL for a project.

git_url

Returns the Git bridge URL for a project.

git_clone, git_pull, git_push, git_remote_add

Run Git using list-form system, avoiding shell interpolation. Direct module use leaves authentication to Git or to a caller-supplied git_runner; the module does not put Overleaf Git authentication tokens on the command line or in remote URLs. The bundled overleaf CLI can supply its standardized token through a temporary GIT_ASKPASS helper.

git_push($directory) retains the ordinary git push behavior. Additional arguments are passed to git push, which lets the command-line client use an explicit Overleaf remote and the remote's discovered default/tracking branch for its higher-level local compile workflow.

AUTHENTICATION

Overleaf divides the functionality used by this distribution across two separate authentication systems. They are not interchangeable:

The official Git bridge uses a Git authentication token. The username is git and the token is the password. Create tokens in Overleaf Account Settings under Git authentication tokens; Overleaf also offers token generation from a project's Integrations - Git> dialog.
The experimental project-listing, ZIP, compile, PDF, and build-output methods use the overleaf_session2 cookie from an already authenticated browser session.

The bundled overleaf CLI standardizes these credentials as:

~/.overleaf/session
~/.overleaf/git-token

and also supports OVERLEAF_SESSION and OVERLEAF_GIT_TOKEN. Run:

overleaf --help

for the complete step-by-step setup, credential precedence, permission rules, independent authentication tests, and the combined Git-push -> Overleaf-compile -> PDF-download workflow.

Official Git bridge

For Overleaf Cloud, create a Git authentication token at:

https://www.overleaf.com/user/settings

under Git authentication tokens, then choose Generate token and copy the complete value when it is displayed. Overleaf does not display the whole token again later; generate a new one if the original value is lost. The first use of a project's Integrations - Git> dialog can also offer Generate token.

Git uses git as the username and the token as the password. The same token can be used across the projects accessible to that account; Overleaf currently documents a one-year expiration period. Each collaborator should use their own token.

Direct module use leaves credential storage to Git or to the caller's git_runner. The bundled CLI additionally supports ~/.overleaf/git-token and OVERLEAF_GIT_TOKEN, passed to Git through GIT_ASKPASS so the token is not embedded in Git URLs or process arguments.

See Overleaf's current token documentation:

https://docs.overleaf.com/integrations-and-add-ons/git-integration-and-github-synchronization/git-integration/git-integration-authentication-tokens

Experimental browser-session operations

The experimental project-listing, ZIP, compile, PDF, and compile-output methods use the same authenticated browser session as the Overleaf web application. The practical authentication method is to copy the value of the overleaf_session2 cookie from a browser in which you are already logged in.

For Firefox, press F12 and open Storage - Cookies -> https://www.overleaf.com>. For Chrome, Edge, and other Chromium-family browsers, open Application - Storage -> Cookies -> https://www.overleaf.com>. Find overleaf_session2 and copy only its Value, not the overleaf_session2= prefix.

The copied value can be supplied directly:

my $ol = Webservice::Overleaf::API->new(
    experimental => 1,
    session      => $session_value,
);

or through the environment:

$ENV{OVERLEAF_SESSION} = $session_value;

my $ol = Webservice::Overleaf::API->new(
    experimental => 1,
);

The CLI's default ~/.overleaf/session file contains that value on exactly one line. Treat it like a password. It grants access as the logged-in Overleaf user and must not be committed, logged, pasted into bug reports, or otherwise disclosed.

Session lifetime

As of the Overleaf Cookie Policy last modified 5 August 2026, overleaf_session2 is an authentication cookie with a documented retention period of 5 days. A copied session value should therefore be treated as a short-lived credential and refreshed from the browser when authentication stops working.

The five-day retention period is not a guarantee that a particular copied session will remain valid for exactly five days. Logging out, revocation, rotation, security changes, or other server-side invalidation may make it stop working earlier.

See https://www.overleaf.com/legal for Overleaf's current cookie policy.

EXPERIMENTAL WEB APPLICATION INTERFACE

These methods require both experimental => 1 and an Overleaf session cookie. OVERLEAF_SESSION is used when session is not passed directly. See "AUTHENTICATION" for the current browser-cookie procedure and session lifetime. Treat this cookie like a password and do not commit or log it.

bootstrap

Fetches the project page and obtains the CSRF token required by state-changing web application requests.

projects

Returns the current non-archived, non-trashed projects as a Util::H2O::More objectified array. It understands the current prefetched-project metadata and older metadata shapes used by older/self-hosted Overleaf releases.

project_zip

Downloads a project ZIP. With to => $filename it writes the bytes to that file; otherwise it returns the bytes.

compile

Compiles a project remotely and returns an object containing status, pdf_url, compile_group, clsi_server_id, and output_files.

An optional resource_path requests that a particular TeX file be treated as the root document for the compile.

download_pdf

Compiles and downloads output.pdf, or accepts a previous compile result via compile => $result. With to => $filename it writes the PDF.

download_output

$ol->download_output($compile, 'output.log', to => 'output.log');

Downloads a named compile artifact from a previous compile result.

COMMAND-LINE CLIENT

The distribution includes overleaf, a command-line companion implemented as a modulino in bin/overleaf. It uses Util::H2O::More::Getopt2h2o for option handling and Dispatch::Fu for command routing.

The CLI exposes the same two broad integration surfaces as the module:

The documented Open in Overleaf interface and Git bridge.
The explicitly opt-in browser-session interface used for project listing, project ZIP download, remote compilation, PDF retrieval, and build artifacts.

For day-to-day work, the CLI standardizes its two private credentials under ~/.overleaf/. Create the directory and files once:

mkdir -p ~/.overleaf
chmod 700 ~/.overleaf

# Copy only the value of the overleaf_session2 browser cookie.
read -rsp 'Paste overleaf_session2 value: ' OL_SESSION; printf '\n'
printf '%s\n' "$OL_SESSION" > ~/.overleaf/session
unset OL_SESSION
chmod 600 ~/.overleaf/session

# Copy only the Overleaf Git authentication token.
read -rsp 'Paste Overleaf Git token: ' OL_GIT_TOKEN; printf '\n'
printf '%s\n' "$OL_GIT_TOKEN" > ~/.overleaf/git-token
unset OL_GIT_TOKEN
chmod 600 ~/.overleaf/git-token

Both files are discovered automatically. Credential files must live below ~/.overleaf/ and should be created with mode 0600; the CLI verifies exact mode where POSIX permissions are enforceable and handles MSYS2/Windows noacl filesystems specially. OVERLEAF_SESSION and OVERLEAF_GIT_TOKEN are supported as environment-variable alternatives.

overleaf --experimental bootstrap

A successful bootstrap prints:

authenticated

List projects and choose the project ID you want to work with:

overleaf --experimental projects

ID=0123456789abcdef

A project ZIP is the easiest way to inspect the source tree:

overleaf --experimental \
    --output project.zip \
    zip "$ID"

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

There are two useful compile forms. The low-level remote form compiles whatever is already present in an Overleaf project and lists build artifacts, not source files:

overleaf --experimental compile "$ID"

The higher-level local form is intended for ordinary work in an Overleaf Git checkout. It discovers the project ID from the Git remote, requires a clean work tree, pushes the complete committed project to Overleaf, compiles the requested root document, and downloads the resulting PDF:

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

overleaf --experimental compile main.tex

The local workflow discovers the Overleaf remote branch from the current branch's upstream or the remote HEAD; it does not hard-code master or main. The complete committed project is pushed as HEAD:<branch>.

This writes main.pdf by default. Omitting main.tex uses Overleaf's configured root and names the PDF from the repository directory. --output selects a different local filename, and --no-push deliberately compiles the existing remote project without synchronizing the local checkout.

The local form treats the Git repository as the working project. It does not try to select only .tex or .bib files: LaTeX builds may depend on style files, classes, images, generated sources, or other tracked resources. The project ZIP remains an export/snapshot used for inspection and backup, not an editable staging mechanism.

The low-level compile PROJECT_ID form prints the compilation status, PDF URL, and generated files such as output.log, output.bbl, output.chktex, and output.pdf.

A useful way to discover the root TeX document used by Overleaf is to retrieve the compilation log and inspect its initial **filename.tex line:

overleaf --experimental \
    --output output.log \
    output "$ID" output.log

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

Once the root is known, it can be requested explicitly:

ROOT_TEX=user_guide.tex

overleaf --experimental \
    --resource-path "$ROOT_TEX" \
    compile "$ID"

Download the resulting PDF:

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

On a Linux desktop:

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

From MSYS2/Git Bash on Windows:

start document.pdf

The Git bridge is separate from the browser-session credential. Git uses Overleaf's token-based Git authentication and its normal credential handling. For a project with Git integration enabled:

overleaf git-url "$ID"
overleaf clone "$ID" my-paper
overleaf pull my-paper

After editing and committing locally, a clone whose branch already tracks the Overleaf remote can normally be pushed with:

overleaf push my-paper

For an existing local Git repository, add Overleaf as a named remote:

overleaf remote-add . "$ID" overleaf
git remote -v

Overleaf's Git bridge represents a single linear project history. The CLI discovers the branch tracked/advertised by the selected remote rather than hard-coding master or main; --remote-branch NAME is available when local Git metadata is insufficient.

The CLI's standard private credentials are ~/.overleaf/session for the browser session and ~/.overleaf/git-token for the Git authentication token. Both should be created with mode 0600. OVERLEAF_SESSION and OVERLEAF_GIT_TOKEN are also supported. See overleaf --help for the complete setup, MSYS2/Windows permission note, and precedence rules.

overleaf --help contains the complete command reference and a more detailed start-to-finish walkthrough.

DISPATCH INTERFACE

call

my $projects = $ol->call('projects');
my $git_url  = $ol->call('git_url', $project_id);

Uses Dispatch::Fu to route a static operation name to the corresponding method. Unsupported names throw an exception.

TESTING

The distribution's tests make no live Overleaf requests. The HTTP client and Git runner are injected and mocked so request methods, URLs, headers, compile bodies, error handling, binary downloads, and dispatch behavior are exercised deterministically.

COMPATIBILITY NOTES

Overleaf documents the Open in Overleaf interface and Git integration. It does not document the ordinary project web application's browser endpoints as a stable public API. The experimental implementation is informed by observable web-client behavior and by the open-source olcli project, which tracks these endpoint changes in practice.

SCIENCE PERL CONTEXT

This distribution is general-purpose, but part of its development grew out of a practical publishing need. The author is a member of the Perl Community's Science Perl Committee and a Co-Editor of the Science Perl Journal, and the Git/Overleaf workflow supported here is useful for some of the ordinary work of preparing, reviewing, and editing LaTeX submissions.

Nothing in this module is required in order to write for the Journal; it is simply tooling that may make an existing Overleaf and Git workflow more convenient. Perl programmers doing scientific, engineering, or other technical work are welcome to learn more about the Science Perl Committee at:

https://perlcommunity.org/science/

The Science Perl Journal can be read online at:

https://science.perlcommunity.org/spj

Prospective authors can find the Journal's submission information at:

https://science.perlcommunity.org/spj/about/submissions

Readers interested in a printed issue can follow the Journal's announcements for current purchase information:

https://science.perlcommunity.org/spj/announcement

AUTHOR

Brett Estrade <oodler@cpan.org>

Member, Perl Community's Science Perl Committee.

Co-Editor, The Science Perl Journal.

LICENSE AND COPYRIGHT

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

To install Webservice::Overleaf::API, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Webservice::Overleaf::API

CPAN shell

perl -MCPAN -e shell
install Webservice::Overleaf::API

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)