{"id":50446210,"url":"https://github.com/academic/homebrew-tap","last_synced_at":"2026-05-31T21:32:59.404Z","repository":{"id":350026210,"uuid":"1203229751","full_name":"academic/homebrew-tap","owner":"academic","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-08T14:40:50.000Z","size":5,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T16:26:34.027Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/academic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-06T21:08:40.000Z","updated_at":"2026-04-08T14:40:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/academic/homebrew-tap","commit_stats":null,"previous_names":["academic/homebrew-tap"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/academic/homebrew-tap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/academic%2Fhomebrew-tap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/academic%2Fhomebrew-tap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/academic%2Fhomebrew-tap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/academic%2Fhomebrew-tap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/academic","download_url":"https://codeload.github.com/academic/homebrew-tap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/academic%2Fhomebrew-tap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33750474,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T21:32:58.788Z","updated_at":"2026-05-31T21:32:59.392Z","avatar_url":"https://github.com/academic.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# academic CLI\n\nThe `academic` CLI is a research workflow tool for managing projects, references, notes, experiments, datasets, paper builds, and submission packaging from one command surface.\n\nIt is designed around reproducibility and low-friction daily use:\n\n- Scaffold consistent project structures.\n- Keep notes, references, and experiments organized.\n- Build LaTeX papers with sensible fallbacks.\n- Track dataset checksums and environment snapshots.\n- Package anonymized or arXiv-ready outputs.\n- Use the same capabilities through CLI, TUI, and local web UI.\n\n## Table Of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Authentication (Browser Login)](#authentication-browser-login)\n- [How Project Detection Works](#how-project-detection-works)\n- [User Configuration](#user-configuration)\n- [Environment Variables](#environment-variables)\n- [Command Reference](#command-reference)\n- [Common Workflows](#common-workflows)\n- [Troubleshooting](#troubleshooting)\n- [Development](#development)\n\n## Installation\n\n### Homebrew (recommended)\n\n```bash\nbrew tap academic/tap\nbrew install academic\nacademic version\n```\n\n\n## Quick Start\n\n```bash\n# 1) Set your defaults once\nacademic config set author \"Jane Doe\"\nacademic config set email \"jane@example.edu\"\nacademic config set license \"MIT\"\n\n# 2) Create a project\nacademic init my-paper --template paper --examples\ncd my-paper\n\n# 3) Verify local setup\nacademic doctor\n\n# 4) Start writing and collecting references\nacademic note today\nacademic ref search diffusion models\nacademic ref add 10.1145/3292500.3330701\n\n# 5) Run an experiment and capture environment\nacademic exp new baseline\nacademic exp run\nacademic env snapshot\n\n# 6) Build and package your paper\nacademic paper build\nacademic share arxiv\n```\n\n## Authentication (Browser Login)\n\n`academic login` implements a browser callback flow:\n\n1. Starts a temporary local callback server on `127.0.0.1` with a random port.\n2. Generates a one-time `state` token.\n3. Builds a login URL (default: `https://academic.io/login`) with callback and state parameters.\n4. Opens your browser unless `--no-open` is set.\n5. Waits for callback query params (`token`, `state`, optional `email`, optional `expires_at`).\n6. Validates state, then saves a local auth session file.\n\nCommands:\n\n```bash\nacademic login\nacademic login --no-open\nacademic login --timeout 5m\nacademic login --login-url \"https://academic.io/login\"\n\nacademic logout\n```\n\nSession storage defaults to:\n\n- `~/.config/academic/auth.yaml` (or `$XDG_CONFIG_HOME/academic/auth.yaml`)\n- Override with `ACADEMIC_AUTH_PATH`\n\nNotes:\n\n- `logout` removes the session file.\n- If login times out, rerun with a higher `--timeout`.\n\n## How Project Detection Works\n\nMany commands (notes, refs, data, experiments, paper, sharing) require being inside an academic project.\n\nProject root detection:\n\n- The CLI walks upward from current directory.\n- First directory containing `.academic/` is treated as project root.\n- Local metadata is read from `.academic/config.yaml`.\n\nIf no root is found, commands that need project context return:\n\n`not inside an academic project (no .academic/config.yaml found)`\n\n## User Configuration\n\nUser config file path:\n\n1. `ACADEMIC_CONFIG` (if set)\n2. `$XDG_CONFIG_HOME/academic/config.yaml`\n3. `~/.config/academic/config.yaml`\n\nSupported keys:\n\n- `author`\n- `email`\n- `orcid`\n- `license`\n- `editor`\n\nExamples:\n\n```bash\nacademic config list\nacademic config path\n\nacademic config set author \"Jane Doe\"\nacademic config set editor \"code -w\"\nacademic config get author\nacademic config unset orcid\n```\n\nHow config is used:\n\n- `init` uses configured `author`, `email`, and `license` defaults.\n- `note` uses configured `editor` if `ACADEMIC_EDITOR` is not set.\n\n## Environment Variables\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `ACADEMIC_CONFIG` | Absolute path for user config file | `$XDG_CONFIG_HOME/academic/config.yaml` or `~/.config/academic/config.yaml` |\n| `ACADEMIC_AUTH_PATH` | Absolute path for auth session YAML | `$XDG_CONFIG_HOME/academic/auth.yaml` or `~/.config/academic/auth.yaml` |\n| `ACADEMIC_LOGIN_URL` | Default login page URL for `academic login` | `https://academic.io/login` |\n| `ACADEMIC_EDITOR` | Preferred editor command for note open actions | Falls back to config key `editor`, then `VISUAL`, then `EDITOR` |\n| `VISUAL` | Editor fallback | none |\n| `EDITOR` | Editor fallback | none |\n| `ACADEMIC_NO_AUTO_INSTALL` | Disable automatic Tectonic download in `paper build` | auto-install enabled |\n| `ACADEMIC_CACHE_DIR` | Custom cache root; used for engine cache (`engines/`) | system user cache directory |\n| `XDG_CONFIG_HOME` | XDG config root for config/auth files | `~/.config` |\n\n## Command Reference\n\n### Top-Level Command Tree\n\n```text\nacademic\n  anonymize\n  citation\n    init\n    update\n  completion\n  config\n    get\n    list\n    path\n    set\n    unset\n  data\n    fetch\n    list\n    verify\n  doctor\n  env\n    snapshot\n  exp\n    diff\n    list\n    new\n    run\n  greet\n  init\n  login\n  logout\n  note\n    link\n    list\n    new\n    search\n    today\n  paper\n    build\n    clean\n    figures\n      sync\n    new\n    wordcount\n  ref\n    add\n    check\n    cite\n    export\n    list\n    search\n  share\n    arxiv\n  tui\n  update\n  version\n  web\n```\n\n### Project Setup And Health\n\n#### `academic init \u003cproject-name\u003e`\n\nScaffolds a project from built-in templates.\n\nTemplates:\n\n- `paper` (default): LaTeX-oriented research layout.\n- `minimal`: lightweight Markdown-oriented layout.\n\nImportant flags:\n\n- `-t, --template`: template name.\n- `-d, --dir`: target directory (default `./\u003cproject-name\u003e`).\n- `--author`, `--email`, `-l, --license`.\n- `--examples`: include starter examples.\n- `--no-git`: skip `git init`.\n- `--force`: allow non-empty target directory.\n- `--list-templates`: print template names and exit.\n\nExamples:\n\n```bash\nacademic init thesis-2026 --template paper --author \"Jane Doe\" --license MIT\nacademic init notes --template minimal --no-git\nacademic init my-study --examples\n```\n\n#### `academic doctor`\n\nChecks external tools and project structure.\n\n- Required tool: `git`.\n- Optional tools checked: `go`, LaTeX engines, `biber`, `pandoc`, `python`, `R`, `jupyter`, `texcount`.\n- Project checks include presence/type of common files and directories.\n- If bibliography exists, performs parse + structural validation.\n\nFlags:\n\n- `--tools-only`\n- `--project-only`\n\n#### `academic config`\n\nSubcommands:\n\n- `config get \u003ckey\u003e`\n- `config set \u003ckey\u003e \u003cvalue\u003e`\n- `config unset \u003ckey\u003e`\n- `config list`\n- `config path`\n\n### Authentication\n\n#### `academic login`\n\nFlags:\n\n- `--login-url` (default from `ACADEMIC_LOGIN_URL` or `https://academic.io/login`)\n- `--timeout` (default `3m`)\n- `--no-open`\n\nBehavior details:\n\n- Binds callback on `127.0.0.1:0`.\n- Saves YAML session with token, email, and timestamps.\n\n#### `academic logout`\n\n- Removes the saved session file.\n- Safe to run when no session exists.\n\n### Notes\n\n#### `academic note today`\n\n- Creates or opens `notes/daily/YYYY-MM-DD.md`.\n- Writes frontmatter on first creation.\n- Opens editor unless `--no-edit`.\n\n#### `academic note new \u003ctitle\u003e`\n\n- Creates `notes/YYYY-MM-DD-\u003cslug\u003e.md`.\n- Supports repeatable tags via `-t, --tag`.\n- Opens editor unless `--no-edit`.\n\n#### `academic note list`\n\n- Recursively lists Markdown files under `notes/`.\n\n#### `academic note search \u003cquery\u003e`\n\n- Case-insensitive substring search across notes.\n- Output format: `path:line: content`.\n- Optional filters:\n  - `-t, --tag` (frontmatter line contains any tag)\n  - `-C, --context \u003cn\u003e`\n\n#### `academic note link \u003cfrom\u003e \u003cto\u003e`\n\n- Resolves note IDs via path/date/slug matching.\n- Appends wiki link `[[target-slug]]` under `## Links`.\n- Deduplicates existing link.\n- `-b, --bidirectional` adds reverse link.\n\nEditor resolution order for note commands:\n\n1. `ACADEMIC_EDITOR`\n2. `config.editor`\n3. `VISUAL`\n4. `EDITOR`\n\n### References\n\n#### `academic ref add \u003cidentifier\u003e`\n\nAccepts:\n\n- DOI (`10.xxxx/...`, `doi:...`, or DOI URL)\n- arXiv ID (`1706.03762`, `arXiv:...`, arXiv abs URL)\n- ISBN (`isbn:...` or compact/hyphenated)\n\nBehavior:\n\n- Fetches entry metadata from Crossref, arXiv, or Open Library.\n- Appends to bibliography file.\n- Refuses duplicate citation key.\n\nFlags:\n\n- `--bib \u003cpath\u003e`\n- `--print` (stdout only)\n\n#### `academic ref check`\n\nChecks:\n\n- Duplicate keys.\n- Missing required fields by entry type.\n- Optional DOI reachability when `--doi` is set.\n\nFlags:\n\n- `--bib \u003cpath\u003e`\n- `--doi`\n\n#### `academic ref list`\n\n- Prints key, entry type, and title summary.\n\n#### `academic ref cite \u003ckey\u003e`\n\n- Prints best-effort APA-style citation for one key.\n\n#### `academic ref search \u003cquery\u003e`\n\n- Queries Crossref works API.\n- Prints DOI, year, authors, and title.\n\nFlag:\n\n- `-n, --limit` (default `10`)\n\n#### `academic ref export [keys...]`\n\n- Export selected keys or all entries (`--all`).\n- Supported formats: `bibtex`, `csl-json`, `ris`.\n- Writes to stdout or `--out` file.\n\nFlags:\n\n- `-f, --format` (default `bibtex`)\n- `--all`\n- `-o, --out`\n- `--bib`\n\nBibliography path resolution:\n\n- If `--bib` is provided, relative path is resolved from project root when possible.\n- Otherwise first existing file is chosen from:\n  - `paper/refs.bib`\n  - `refs.bib`\n  - `references.bib`\n  - `bibliography.bib`\n- If none exists, default target becomes `paper/refs.bib`.\n\n### Data\n\n#### `academic data fetch [url]`\n\nDownloads data and records manifest metadata.\n\nCapabilities:\n\n- Direct URL fetch.\n- DOI-based fetch via DataCite with `--doi`.\n- SHA-256 computation and file size capture.\n- Upsert to `data/manifest.json`.\n\nFlags:\n\n- `--doi \u003cdoi\u003e`\n- `--to \u003cproject-relative-path\u003e`\n- `--force`\n\n#### `academic data list`\n\n- Lists manifest entries (`sha-prefix size path`).\n\n#### `academic data verify`\n\n- Re-hashes files listed in manifest.\n- Reports `OK`, `MISSING`, or checksum mismatch.\n- Returns non-zero exit on any failure.\n\n### Experiments And Reproducibility\n\n#### `academic exp new \u003cname\u003e`\n\nCreates `experiments/YYYY-MM-DD-\u003cslug\u003e/` with:\n\n- `config.yaml`\n- `NOTES.md`\n- `run.sh` (executable)\n- `results/.gitkeep`\n- `.gitignore` scoped to experiment results\n\nIncludes current git SHA when available.\n\n#### `academic exp list`\n\n- Lists experiment directories sorted by name.\n\n#### `academic exp run [name]`\n\n- Runs chosen experiment `run.sh`.\n- If omitted, runs latest experiment.\n- Captures stdout/stderr to `results/run.log`.\n- Writes runtime metadata to `results/env.txt`.\n\n#### `academic exp diff \u003ca\u003e \u003cb\u003e`\n\n- Compares:\n  - `config.yaml`\n  - `results/env.txt`\n  - file sets and sizes under each `results/`\n\n#### `academic env snapshot [experiment]`\n\nCaptures environment details into `results/env.txt`, including:\n\n- timestamp, OS, architecture\n- git SHA/branch/dirty state\n- tool versions (if present)\n- `pip freeze`\n- `go.mod`\n- `requirements.txt`\n- truncated `renv.lock` when present\n\nFlag:\n\n- `--stdout` to print instead of writing file\n\n### Paper Authoring\n\n#### `academic paper build`\n\nBuild order:\n\n1. `latexmk -pdf`\n2. `tectonic`\n3. `pdflatex`\n\nIf no builder is found:\n\n- Auto-installs a cached Tectonic binary by default.\n- Disable auto-install with `--no-auto-install` or `ACADEMIC_NO_AUTO_INSTALL=1`.\n\nFlags:\n\n- `--main \u003cpath\u003e` (default lookup starts with `paper/main.tex`)\n- `--no-auto-install`\n\n#### `academic paper clean`\n\n- Removes common LaTeX artifacts (`.aux`, `.bbl`, `.log`, etc.).\n\nFlag:\n\n- `--main`\n\n#### `academic paper wordcount`\n\n- Uses `texcount` when available.\n- Falls back to approximate parser over included TeX files.\n\nFlag:\n\n- `--main`\n\n#### `academic paper figures sync`\n\n- Mirrors figure assets from source to destination.\n- Uses SHA-256 to avoid copying unchanged files.\n- Optional delete of destination files absent in source.\n\nFlags:\n\n- `--src` (default `results/figures`)\n- `--dst` (default `paper/figures`)\n- `--delete`\n- `--dry-run`\n\n#### `academic paper new \u003cname\u003e`\n\nScaffolds standalone paper directory templates:\n\n- `ieee`\n- `acm`\n- `elsevier`\n- `springer`\n- `thesis`\n\nFlags:\n\n- `-t, --template` (default `ieee`)\n- `-d, --dir` (default `paper-\u003cname\u003e`)\n- `--force`\n\nGenerated files include `main.tex`, `refs.bib`, `README.md`, `sections/`, and `figures/`.\n\n### Sharing And Metadata\n\n#### `academic citation init`\n\n- Creates `CITATION.cff` from project metadata.\n- Uses best-effort author name split into `given-names` and `family-names`.\n\nFlag:\n\n- `--force`\n\n#### `academic citation update`\n\n- Rewrites citation metadata and updates release date.\n\n#### `academic anonymize`\n\nFor blind submission, rewrites LaTeX content by removing or replacing common identity-bearing fields:\n\n- `\\author{}`\n- `\\affil{}` / `\\affiliation{}` / `\\institute{}`\n- `\\thanks{}`\n- `\\email{}` / `\\orcid{}`\n- `\\address{}`\n- acknowledgements sections/environments\n\nFlags:\n\n- `--main`\n- `--out`\n- `--in-place`\n\nDefault output is `\u003cmain\u003e.anon.tex`.\n\n#### `academic share arxiv`\n\nBuilds a `.tar.gz` containing paper source and needed assets while skipping PDF/build artifacts.\n\nFlags:\n\n- `--main`\n- `--out` (default `dist/arxiv-YYYYMMDD.tar.gz`)\n\n### Interactive Interfaces\n\n#### `academic tui`\n\n- Bubble Tea terminal UI.\n- Presents common actions for project, refs, notes, experiments, data, paper, and sharing.\n- Executes the same `academic` binary commands under the hood.\n\n#### `academic web`\n\n- Starts local web UI server (default `127.0.0.1:8765`).\n- Scans root directory for projects (`.academic/` folders).\n- Exposes command execution, file tree browsing, and basic file editing.\n\nFlags:\n\n- `--addr \u003chost:port\u003e`\n- `--root \u003cdirectory\u003e`\n\n### Utility Commands\n\n#### `academic completion [bash|zsh|fish|powershell]`\n\nGenerate completion scripts.\n\nExamples:\n\n```bash\n# bash\nsource \u003c(academic completion bash)\n\n# zsh\nsource \u003c(academic completion zsh)\n\n# fish\nacademic completion fish | source\n```\n\n#### `academic update`\n\n- Self-updates from GitHub releases.\n- Works only for non-dev builds (version must not be `dev`).\n\n#### `academic version`\n\n- Prints CLI version.\n\n#### `academic greet \u003cname\u003e`\n\n- Simple greeting command.\n- `-u, --upper` for uppercase output.\n\n## Common Workflows\n\n### Workflow: New Paper Project\n\n```bash\nacademic config set author \"Jane Doe\"\nacademic config set email \"jane@example.edu\"\n\nacademic init causality-paper --template paper --examples\ncd causality-paper\n\nacademic note today\nacademic ref add 10.1038/nature14539\nacademic paper build\n```\n\n### Workflow: Data Integrity + Experiment Reproducibility\n\n```bash\nacademic data fetch --doi 10.5281/zenodo.1234567\nacademic data verify\n\nacademic exp new baseline\nacademic exp run baseline\nacademic env snapshot baseline\nacademic exp diff baseline baseline\n```\n\n### Workflow: Blind Submission + arXiv Package\n\n```bash\nacademic anonymize --main paper/main.tex --out paper/main.blind.tex\nacademic share arxiv --main paper/main.tex\nacademic citation update\n```\n\n## Troubleshooting\n\n### \"not inside an academic project\"\n\n- Run `academic init \u003cname\u003e` first, or\n- `cd` into a folder containing `.academic/config.yaml`.\n\n### `paper build` cannot find a LaTeX engine\n\n- Allow auto-install (default), or\n- Install `latexmk`, `tectonic`, or `pdflatex` manually, or\n- Pass `--no-auto-install` only if you already have a local engine.\n\n### `login` times out\n\n- Increase timeout: `academic login --timeout 10m`.\n- Use `--no-open` and open printed URL manually.\n\n### `ref add` duplicate key error\n\n- Existing key already in bibliography.\n- Use `ref list`/`ref check` to inspect current entries and resolve conflicts.\n\n### `data verify` reports mismatch\n\n- File contents changed since original fetch.\n- Re-fetch with `--force` or intentionally update manifest by fetching again.\n\n### Notes do not open in editor\n\n- Set one of:\n  - `ACADEMIC_EDITOR`\n  - `academic config set editor \"\u003ccommand\u003e\"`\n  - `VISUAL` / `EDITOR`\n- Use `--no-edit` if you only want file creation.\n\n## Development\n\n### Build And Test\n\n```bash\ngo build ./...\ngo test -race ./...\n```\n\n### Run Locally\n\n```bash\ngo run . --help\ngo run . init demo\n```\n\n### Release Notes\n\n- CI builds multi-platform artifacts on release publication.\n- Homebrew formula template is in `academic.rb`.\n- `update` relies on versioned (non-dev) binaries.\n\n## Notes\n\n- `academic` is intentionally command-first. TUI and web UI are wrappers over the same command actions.\n- For command-level details, run `academic \u003ccommand\u003e --help`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facademic%2Fhomebrew-tap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facademic%2Fhomebrew-tap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facademic%2Fhomebrew-tap/lists"}