Article CLI

A command-line tool for managing LaTeX and Typst documents with git integration and Zotero bibliography synchronization.

Features

Repository Initialization: Complete setup for LaTeX or Typst projects with one command
Project Types: Support for articles, Beamer presentations, posters, and Typst documents
LaTeX Compilation: Compile documents with latexmk/pdflatex/xelatex/lualatex, watch mode, shell escape support
Typst Compilation: Full support for Typst documents with watch mode and custom font paths
Font Installation: Download and install fonts for XeLaTeX projects (Marianne, Roboto Mono, etc.)
GitHub Actions Workflows: Automated PDF compilation with XeLaTeX support, artifact upload, and GitHub releases
Git Release Management: Create, list, and delete releases with gitinfo2 support
Zotero Integration: Synchronize bibliography from Zotero with robust pagination and error handling
Lifecycle Commands: Use init, setup, doctor, bib update, compile, version, and release
LaTeX Build Management: Clean build files and manage LaTeX compilation artifacts
Git Hooks Setup: Automated setup of git hooks for gitinfo2 integration
Repository Diagnostics: doctor checks for git, hooks, build tools, Zotero, workflows, release readiness, and safe repairs with --fix
Project Configuration: Auto-generates pyproject.toml with article-cli settings
Documentation: Creates project README files and ships an Antora documentation site

Installation

From PyPI (recommended)

uv tool install article-cli

From Source

git clone https://github.com/feelpp/article.cli.git
cd article.cli
uv sync --all-extras --dev
uv run article-cli --help

Development Commands

uv sync --all-extras --dev
uv run pytest
uv run black --check src tests
uv run mypy src
uv build

Documentation Site

The documentation site is built with Antora and the Feel++ Antora UI bundle:

npm install
npm run docs:build
npm run docs:preview

The generated site is written to build/site.

Quick Start

For New Projects

Initialize your LaTeX article repository:
```
cd your-article-repo
article-cli init --title "Your Article Title" --authors "Author One,Author Two"
```
This creates:
- .github/workflows/latex.yml - Complete CI/CD pipeline
- pyproject.toml - Project configuration with article-cli settings
- README.md - Documentation and usage instructions
- .gitignore - LaTeX-specific ignore rules
- .vscode/settings.json - LaTeX Workshop configuration
- .vscode/ltex.dictionary.en-US.txt - Custom dictionary

Configure Zotero (add as GitHub secret):

export ZOTERO_API_KEY="your_api_key_here"

Setup git hooks and update bibliography:

article-cli doctor
article-cli doctor --fix
article-cli setup --dry-run
article-cli setup
article-cli bib update --dry-run
article-cli bib update

Commit and push to trigger automated PDF compilation!

For Existing Projects

Setup git hooks (run once per repository):

article-cli doctor
article-cli doctor --fix
article-cli setup

Configure Zotero credentials:

export ZOTERO_API_KEY="your_api_key_here"
export ZOTERO_GROUP_ID="your_group_id"  # or ZOTERO_USER_ID

Update bibliography from Zotero:
```
article-cli bib update
```

Compile, refresh version metadata, and create a release:

article-cli compile
article-cli version
article-cli release v1.0.0 --dry-run
article-cli release v1.0.0

Configuration

Environment Variables

ZOTERO_API_KEY: Your Zotero API key (required for bibliography updates)
ZOTERO_USER_ID: Your Zotero user ID (alternative to group ID)
ZOTERO_GROUP_ID: Your Zotero group ID (alternative to user ID)

Local Configuration File

Create a .article-cli.toml file in your project root for project-specific settings:

[zotero]
api_key = "your_api_key_here"
group_id = "4678293"  # Default for article.template
# user_id = "your_user_id"  # alternative to group_id
output_file = "references.bib"

[git]
auto_push = false
default_branch = "main"

[workflow]
runner_policy = "github"
github_runner = "ubuntu-24.04"
self_hosted_label = "self-texlive"
self_hosted_org = ""
bibliography = "off"
release = "github"
artifact_includes = []

[latex]
clean_extensions = [".aux", ".bbl", ".blg", ".log", ".out", ".synctex.gz"]

[fonts]
directory = "fonts"

[fonts.sources]
marianne = "https://github.com/ArnaudBelcworking/Marianne/archive/refs/heads/master.zip"
roboto-mono = "https://github.com/googlefonts/RobotoMono/releases/download/v3.000/RobotoMono-v3.000.zip"

[themes]
directory = "."

# Custom theme sources (numpex is built-in)
# [themes.sources.my-theme]
# url = "https://example.com/theme.zip"
# description = "My custom theme"
# files = ["beamerthememytheme.sty"]
# typst_files = ["mytheme.typ"]
# requires_fonts = false
# engine = "pdflatex"

[typst]
font_paths = ["fonts/", "~/.fonts/"]
build_dir = "build"

Usage

Repository Initialization

# Initialize a new article repository (auto-detects main .tex file)
article-cli init --title "My Article Title" --authors "John Doe,Jane Smith"

# Initialize a Beamer presentation project
article-cli init --title "My Presentation" --authors "Author" --type presentation

# Initialize with numpex theme (requires theme files from presentation.template.d)
article-cli init --title "NumPEx Talk" --authors "Author" --type presentation --theme numpex

# Initialize a Typst presentation project
article-cli init --title "My Typst Talk" --authors "Author" --type typst-presentation

# Initialize a Typst poster project
article-cli init --title "My Typst Poster" --authors "Author" --type typst-poster

# Specify custom Zotero group ID
article-cli init --title "My Article" --authors "Author" --group-id 1234567

# Specify main .tex file explicitly
article-cli init --title "My Article" --authors "Author" --tex-file article.tex

# Force overwrite existing files
article-cli init --title "My Article" --authors "Author" --force

# Generate CI that checks Zotero bibliography freshness
article-cli init --title "My Article" --authors "Author" --ci-bib check

# Generate CI with opt-in self-hosted runner discovery
article-cli init --title "My Article" --authors "Author" \
  --ci-runner-policy self-hosted-auto --ci-self-hosted-org my-org

The init command sets up:

GitHub Actions workflow for automated PDF compilation and releases (with XeLaTeX support for presentations)
pyproject.toml with dependencies and article-cli configuration
README.md with comprehensive documentation
.gitignore with LaTeX-specific patterns
VS Code configuration for LaTeX Workshop with auto-build and SyncTeX
Font configuration (for presentation projects using custom themes)

Git Release Management

# Refresh paper version metadata (LaTeX or Typst)
article-cli version

# Refresh metadata, compile, and check the PDF version text
article-cli version --compile --check-pdf

# Preview a new release tag
article-cli release v1 --dry-run

# Create a checked local release tag
article-cli release v1

# Check bibliography freshness during release, then push the tag
article-cli release v1 --bib check --push

# List recent releases
article-cli list --count 10

# Delete a release
article-cli delete v1.2.3

# Deprecated alias retained for compatibility
article-cli create v1.2.3

Bibliography Management

# Preview bibliography update
article-cli bib update --dry-run

# Update bibliography from Zotero
article-cli bib update

# Specify custom output file
article-cli bib update --output my-refs.bib

# Skip backup creation
article-cli bib update --no-backup

# Deprecated alias retained for compatibility
article-cli update-bibtex

LaTeX Compilation

# Compile with latexmk (default engine)
article-cli compile

# Compile specific file with latexmk
article-cli compile main.tex

# Compile with pdflatex engine
article-cli compile --engine pdflatex

# Compile with XeLaTeX (for custom fonts)
article-cli compile --engine xelatex

# Compile with LuaLaTeX
article-cli compile --engine lualatex

# Enable shell escape (for code highlighting, etc.)
article-cli compile --shell-escape

# Watch for changes and auto-recompile
article-cli compile --watch

# Clean before and after compilation
article-cli compile --clean-first --clean-after

# Specify output directory
article-cli compile --output-dir build/

Paper Version Metadata

article-cli version writes LaTeX's gitHeadLocal.gin for gitinfo2, or a portable gitHeadLocal.json snapshot beside a Typst main document. The Typst snapshot contains the commit, short hash, branch, description, nearest tag, commit date, and dirty flag. Generated metadata is excluded from dirty detection; tracked source changes count as dirty, matching the existing LaTeX behavior. --dry-run reports planned changes without writing files.

\usepackage[local]{gitinfo2}
% In the document body:
Version: \gitDescribe{} / \gitAbbrevHash{}

#let git = json("gitHeadLocal.json")
#set page(footer: align(center)[Version: #git.description])

New built-in templates include a version stamp. Typst compilation refreshes its snapshot when Git is available; extracted source archives keep their frozen snapshot. Typst reads JSON directly, so no extra Typst package is needed.

article-cli version --document main.typ --compile --check-pdf --checksum
article-cli version --document main.tex --compile --check-pdf

Submission Source Bundles (LaTeX and Typst)

# Build and package the main document and its recorded dependencies
article-cli bundle main.tex --verify
article-cli bundle main.typ --verify

# Preview an existing build without changing any files
article-cli bundle main.tex --dry-run

# Extend project policy for one archive
article-cli bundle main.tex --include 'supplement/**' --exclude 'reviews/**' -o dist/preprint.zip

bundle automatically selects a LaTeX or Typst backend. LaTeX uses latexmk and TeX recorder data; Typst 0.14+ uses native JSON dependency reporting, including dynamically loaded data, imports, figures, and bibliography styles. The command writes a reproducible ZIP and an adjacent JSON manifest with file hashes. --verify recompiles only the selected files in a temporary directory before publishing the archive. Both formats share the same selection and output policy.

[tool.article-cli.bundle]
output = "dist/preprint.zip"
include = ["supplement/**"]
exclude = ["reviews/**", "local-only/**"]
include_pdf = false
verify = true

Paths and globs are relative to the main document's directory, which becomes the ZIP root. Include patterns add files to detected dependencies; CLI patterns extend those in configuration. Exclusions take precedence, and excluding a required source fails with an explanation. ** matches any number of directories.

Git repository internals, virtual environments, local-only, .env files, and build logs are excluded by default. The main PDF is excluded unless --include-pdf is set; figure PDFs remain included. Keep all local dependencies and the build directory under the main document's directory. System TeX packages are supplied by the receiving service. LaTeX shell escape is disabled.

Typst imports from external versioned packages are copied, with their manifests and license files, under .article-cli/typst-packages. Configured local [tool.article-cli.typst].font_paths must be under the document directory; font files are included and their relative search paths recorded in the manifest. System fonts remain environment dependencies. To compile an extracted Typst bundle:

typst compile --root . --package-path .article-cli/typst-packages main.typ
# Add --font-path fonts when the bundle uses a configured local font directory.

Use --build-dir build --no-build to reuse existing LaTeX .fls/.aux/.bbl data or Typst <document>.typst-deps.json metadata, or --force to replace an existing ZIP and manifest. Typst dependency metadata is generated by bundle; a previous plain compile does not create it. Dry runs require existing metadata. --no-verify and --no-include-pdf override project policy. Verification checks local compilability; HAL/arXiv still apply their own submission and supported-format requirements. This command prepares files without uploading them.

Run article-cli version before bundling when you need an up-to-date provenance stamp. Bundling preserves the selected snapshot during compilation and verification.

Typst Compilation

# Compile a Typst document (auto-detects .typ files)
article-cli compile presentation.typ

# Compile with explicit Typst engine
article-cli compile --engine typst document.typ

# Watch for changes and auto-recompile
article-cli compile presentation.typ --watch

# Specify custom font paths
article-cli compile presentation.typ --font-path fonts/

# Multiple font paths
article-cli compile presentation.typ --font-path fonts/ --font-path ~/.fonts/

# Specify output directory
article-cli compile presentation.typ --output-dir build/

Note: The engine is automatically detected from the file extension:

.tex files use LaTeX engines (latexmk by default)
.typ files use the Typst engine

Font Installation

Install fonts for XeLaTeX projects (useful for custom Beamer themes):

# Install default fonts (Marianne, Roboto Mono) to fonts/ directory
article-cli install-fonts

# Install to a custom directory
article-cli install-fonts --dir custom-fonts/

# Force re-download even if fonts exist
article-cli install-fonts --force

# List installed fonts
article-cli install-fonts --list

Default fonts:

Marianne: French government official font
Roboto Mono: Google's monospace font for code

Theme Installation

Install Beamer themes for presentations:

# List available themes
article-cli install-theme --list

# Install numpex theme (NumPEx Beamer theme)
article-cli install-theme numpex

# Install to a custom directory
article-cli install-theme numpex --dir themes/

# Force re-download even if theme exists
article-cli install-theme numpex --force

# Install from a custom URL
article-cli install-theme my-theme --url https://example.com/theme.zip

Available themes:

numpex: NumPEx theme following French government visual identity
- LaTeX: Beamer theme files (requires XeLaTeX and custom fonts)
- Typst: numpex.typ theme file for Typst presentations

Complete LaTeX presentation setup:

# 1. Install the theme
article-cli install-theme numpex

# 2. Install required fonts
article-cli install-fonts

# 3. Compile with XeLaTeX
article-cli compile presentation.tex --engine xelatex

Complete Typst presentation setup:

# 1. Install the theme (includes numpex.typ)
article-cli install-theme numpex

# 2. Compile with Typst
article-cli compile presentation.typ --font-path fonts/

Project Setup

# Diagnose repository readiness without modifying files
article-cli doctor

# Emit machine-readable diagnostics for CI
article-cli doctor --json

# Apply safe repairs for hooks, output directories, and gitHeadLocal.gin
article-cli doctor --fix

# Setup git hooks for gitinfo2
article-cli setup

# Clean LaTeX build files
article-cli clean

Advanced Usage

# Override configuration via command line
article-cli bib update --api-key YOUR_KEY --group-id YOUR_GROUP

# Specify custom configuration file
article-cli --config custom-config.toml bib update

Release Tags

The default paper release policy accepts short and full version tags:

vX for paper milestones (e.g., v1)
vX.Y or vX.Y.Z for more detailed paper releases
vX.Y.Z-rc.N, vX.Y.Z-beta.N, or similar pre-release suffixes

Use [tool.article-cli.release] tag_policy = "semver" when a repository must require strict vX.Y.Z semantic-version tags. The release command does not commit, force-retag, push, or create a GitHub release unless the corresponding explicit flag is passed.

Requirements

Python 3.11+
Git repository with gitinfo2 package (for LaTeX integration)
Zotero account with API access (for bibliography features)
Typst CLI (for Typst compilation) - install from https://typst.app/
Node.js 20+ for building the Antora documentation site

License

MIT License - see LICENSE file for details.

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Changelog

v2.1.0

Require Python 3.11+ and use its built-in TOML parser
Add LaTeX and Typst submission bundles and portable paper version metadata

v2.0.1

Keep Python package, generated-template minimum version, Antora component version, docs package version, and lockfiles synchronized
Add a release-version bump script and CI test to prevent stale documentation version labels

v2.0.0

Treat the paper lifecycle as explicit commands: init, setup, doctor, bib update, compile, version, and release
Add safe doctor --fix repairs for output directories, managed git hooks, and gitHeadLocal.gin
Make release the checked paper release workflow and keep create as a deprecated compatibility alias
Drop Python 3.8 support; test Python 3.9 through 3.13
Move generated templates and workflows to package Jinja2 resources
Add Antora documentation with Feel++ Antora UI

v1.5.0

Add doctor diagnostics with JSON output and safe --fix repairs
Split CLI implementation into command modules
Make setup hooks more robust and worktree-safe
Standardize development and CI workflows on uv
Add an Antora documentation site using the Feel++ Antora UI

v1.4.0

Add full Typst document compilation support
New TypstCompiler class for Typst documents
Auto-detection of .typ files with automatic engine selection
Watch mode for Typst with live recompilation
Custom font path support (--font-path option)
New project types: typst-presentation and typst-poster
Theme installation now includes Typst files (e.g., numpex.typ)
Typst configuration section in config files

v1.3.0

Add theme installation command (install-theme) for Beamer presentations
Built-in support for numpex theme with automatic download
Extended GitHub Actions workflow with XeLaTeX and multi-document support

v1.2.0

Add font installation command (install-fonts) for XeLaTeX projects
Support Marianne and Roboto Mono fonts by default
Add presentation project type with Beamer template support
Add --engine option for xelatex and lualatex compilation
Improved CI/CD with font installation steps

v1.1.0

Add init command for repository initialization
Add compile command with watch mode and multiple engines
GitHub Actions workflow generation
VS Code configuration generation

v1.0.0

Initial release
Git release management
Zotero bibliography synchronization
LaTeX build file cleanup
Configuration file support

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
scripts		scripts
src/article_cli		src/article_cli
tests		tests
.flake8		.flake8
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
PYPI_SETUP.md		PYPI_SETUP.md
README.md		README.md
SOLUTION-SUMMARY.md		SOLUTION-SUMMARY.md
antora-playbook.yml		antora-playbook.yml
build-and-test.sh		build-and-test.sh
migrate-repository.sh		migrate-repository.sh
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
upload-to-pypi.sh		upload-to-pypi.sh
uv.lock		uv.lock

Latest commit

History

Folders and files

Repository files navigation