/ 
Webservice-Overleaf-API-0.01
/ 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.

A single trailing newline is removed.

--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

Git bridge

Git operations use Git's own authentication facilities.

For Overleaf Cloud, a Git authentication token can be used by Git as the password for the git user. Store that credential using an appropriate Git credential helper rather than embedding it in a repository URL or command line.

Experimental browser-session operations

Experimental project and compile operations use the Overleaf browser session.

The preferred non-interactive form is:

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

Alternatively:

overleaf --experimental --session-file ~/.config/overleaf/session projects

--session is supported for completeness but is less desirable because process arguments may be observable.

ENVIRONMENT

OVERLEAF_SESSION

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

EXAMPLES

List projects:

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.