/ 
Webservice-Overleaf-API-0.03
/ 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' > session.out
chmod 600 session.out

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 ./session.out 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.

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' > session.out
chmod 600 session.out

List projects using that file:

overleaf --experimental --session-file ./session.out 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.