Academic CLI

A complete command-line workflow for research projects.

The Academic CLI helps you scaffold projects, manage references and notes, run reproducible experiments, verify data integrity, build papers, and prepare submission artifacts from one consistent command surface.

Install

Homebrew (recommended)

$ brew tap academic/tap $ brew install academic $ academic version

Quick start

From zero to running project

academic config set author "Jane Doe" academic config set email "[email protected]" academic init my-paper --template paper --examples cd my-paper academic doctor academic note today academic ref add 10.1145/3292500.3330701 academic exp new baseline academic exp run academic paper build

Authentication

Browser login callback flow

  1. academic login starts a local callback server on 127.0.0.1.
  2. A one-time state token is generated to protect callback integrity.
  3. Your browser opens the login page (or use --no-open).
  4. CLI waits for callback params: token, state, optional email and expiry.
  5. Session is stored locally at ~/.config/academic/auth.yaml by default.
academic login academic login --timeout 10m academic login --no-open academic logout

Project model

How context is resolved

  • Commands walk upward from current directory to find .academic/.
  • Project metadata is read from .academic/config.yaml.
  • If no root is found, project-scoped commands fail with a clear message.

Useful checks

academic doctor academic doctor --project-only academic doctor --tools-only

User configuration

Defaults for daily use

Configure user-level defaults once, then let init and note workflows pick them up automatically.

academic config list academic config path academic config set author "Jane Doe" academic config set editor "code -w" academic config set license "MIT"
  • Supported keys: author, email, orcid, license, editor.
  • Config lookup: ACADEMIC_CONFIG, then $XDG_CONFIG_HOME/academic/config.yaml, then ~/.config/academic/config.yaml.

Environment variables

Most important runtime overrides

ACADEMIC_CONFIG

Absolute path to user config file.

ACADEMIC_AUTH_PATH

Absolute path to login session YAML.

ACADEMIC_LOGIN_URL

Default URL used by academic login.

ACADEMIC_EDITOR

Editor override for note commands (fallbacks: config.editor, VISUAL, EDITOR).

ACADEMIC_NO_AUTO_INSTALL

Disables auto-download of Tectonic in paper build.

ACADEMIC_CACHE_DIR

Custom cache root for managed engine binaries.

Command map

Top-level capabilities

academic init academic doctor academic config academic login academic logout academic note academic ref academic data academic exp academic env snapshot academic paper academic citation academic anonymize academic share arxiv academic tui academic web academic completion academic update academic version

Notes

Daily and topic notes, full-text search, and wiki-style links across notes.

academic note today academic note new "Topic" academic note search diffusion academic note link daily idea -b

References

Add entries by DOI/arXiv/ISBN, validate bibliography quality, search Crossref, and export BibTeX, CSL-JSON, or RIS.

academic ref add 10.1038/nature14539 academic ref search diffusion models -n 5 academic ref check --doi academic ref export --format csl-json --all

Data

Fetch remote datasets, write manifest metadata, and verify checksums for reproducible runs.

academic data fetch --doi 10.5281/zenodo.1234567 academic data list academic data verify

Experiments

Scaffold experiment directories, run scripts, compare runs, and capture environment snapshots.

academic exp new baseline academic exp run baseline academic env snapshot baseline academic exp diff baseline ablation

Paper

Build with latexmk/tectonic/pdflatex fallback, count words, clean artifacts, and sync generated figures.

academic paper build academic paper wordcount academic paper figures sync --dry-run academic paper clean

Submission

Update citation metadata, anonymize author fields for blind review, and produce arXiv-ready bundles.

academic citation update academic anonymize --main paper/main.tex academic share arxiv --main paper/main.tex

Common workflows

Production-ready command sequences

New paper project

academic init causality-paper --template paper --examples cd causality-paper academic note today academic ref add 10.1038/nature14539 academic paper build

Data integrity + reproducibility

academic data fetch --doi 10.5281/zenodo.1234567 academic data verify academic exp new baseline academic exp run baseline academic env snapshot baseline

Blind submission + arXiv package

academic anonymize --main paper/main.tex --out paper/main.blind.tex academic share arxiv --main paper/main.tex academic citation update

Troubleshooting

Fast fixes for common issues

  • Not inside a project: run academic init <name> or change into a folder containing .academic/config.yaml.
  • No LaTeX engine: allow auto-install during paper build or install latexmk/tectonic/pdflatex.
  • Login timeout: retry with academic login --timeout 10m and optionally --no-open.
  • Duplicate citation key: inspect keys with academic ref list and validate with academic ref check.
  • Checksum mismatch: file changed after fetch; rerun with academic data fetch --force when intentional.
  • Editor not launching: set ACADEMIC_EDITOR or configure academic config set editor "...".

Interfaces

academic tui academic web --addr 127.0.0.1:8765
Back to home