ScholarAIO

https://zimoliao.github.io/scholaraio/
Admin
ScholarAIO is an academic harness for AI agents that provides durable context, PDF ingestion, hybrid...
Tokens:73,151
Snippets:566
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and set up ScholarAIO

Source: https://zimoliao.github.io/scholaraio

Install the full ScholarAIO package and run the initial setup command. This is the recommended quick start for users, while contributors should use the editable install path described in the installation guide.

```bash
pip install "scholaraio[full]"
scholaraio setup
```

--------------------------------

### Clone and set up ScholarAIO repository

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

Run these commands in order to clone the repository, install it with full extras, and run the setup command. This is the recommended path for trying ScholarAIO, inspecting the codebase, or contributing.

```bash
git clone https://github.com/ZimoLiao/scholaraio.git
cd scholaraio
pip install -e ".[full]"
scholaraio setup
```

--------------------------------

### One-time setup: clone, install, and initialize ScholarAIO

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

Clones the ScholarAIO repository to a stable location, installs it with full extras, and runs the initial setup. This is the first step for manual fallback.

```bash
git clone https://github.com/ZimoLiao/scholaraio.git ~/.codex/scholaraio
cd ~/.codex/scholaraio
pip install -e ".[full]"
scholaraio setup

```

--------------------------------

### Run scholaraio setup

Source: https://zimoliao.github.io/scholaraio/getting-started/installation

Run the interactive setup wizard to configure API keys and directories.

```bash
scholaraio setup
```

--------------------------------

### Windows: clone and install ScholarAIO

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

Clones the ScholarAIO repository to a stable location on Windows, installs it with full extras, and runs the initial setup. Use this before creating a junction.

```powershell
git clone https://github.com/ZimoLiao/scholaraio.git "$env:USERPROFILE\.codex\scholaraio"
cd "$env:USERPROFILE\.codex\scholaraio"
pip install -e ".[full]"
scholaraio setup

```

--------------------------------

### scholaraio setup commands

Source: https://zimoliao.github.io/scholaraio/guide/cli-reference

Runs the interactive setup wizard, checks dependency/parser/API-key/optional-service/runtime status, previews agent integration, applies automatic agent integration steps, and reports current agent-integration state. After --apply, restart the target agent session. Use --target-project to write project-local wrappers with absolute paths.

```bash
scholaraio setup
scholaraio setup check
scholaraio setup agent
scholaraio setup agent --apply
scholaraio setup agent check

```

--------------------------------

### Upgrade from 2.0.0 Beta 1: Source checkout reinstall

Source: https://zimoliao.github.io/scholaraio/getting-started/upgrading-to-2.0

For a beta source checkout, fetch the stable tag and reinstall from that clean checkout. Run setup check after installation.

```bash
git fetch origin --tags
git checkout v2.0.0
python -m pip install -e ".[full]"
scholaraio setup check
```

--------------------------------

### Example prompts for /nature-workflow

Source: https://zimoliao.github.io/scholaraio/guide/nature-workflow-quickstart

Five example prompts demonstrating different use cases for the /nature-workflow command, from polishing an abstract to simulating a reviewer critique.

```text
/nature-workflow Polish this abstract in Nature Communications style.

```

```text
/nature-workflow Use Python to create a Nature-style multi-panel figure from these benchmark results.

```

```text
/nature-workflow Turn this PDF into a Chinese journal-club PPT.

```

```text
/nature-workflow Draft a Data Availability statement and repository plan for this manuscript.

```

```text
/nature-workflow Simulate a Nature-style reviewer critique for this draft.

```

--------------------------------

### Install scholaraio from PyPI

Source: https://zimoliao.github.io/scholaraio/getting-started/installation

Install the core package from PyPI, or use the [full] extra to include embed, topics, import, pdf, and office extras.

```bash
pip install scholaraio

pip install "scholaraio[full]"
```

--------------------------------

### scholaraio setup agent preview, apply, and check commands

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

Shows the basic usage of the `scholaraio setup agent` command. By default it is a preview and does not modify files; add `--apply` to perform automatic actions. Use `check` to inspect status.

```bash
scholaraio setup agent
scholaraio setup agent --apply
scholaraio setup agent check

```

--------------------------------

### Install scholaraio from source

Source: https://zimoliao.github.io/scholaraio/getting-started/installation

Clone the repository and install in editable mode for core or full extras. Use this path to inspect or edit the codebase locally.

```bash
git clone https://github.com/zimoliao/scholaraio.git
cd scholaraio

pip install -e .

pip install -e ".[full]"
```

--------------------------------

### Manually install local Nature Skills by cloning and copying directories

Source: https://zimoliao.github.io/scholaraio/guide/nature-workflow-quickstart

Clones the upstream repository and copies all skill directories into ~/.codex/skills. Copying only SKILL.md is not enough.

```bash
git clone https://github.com/Yuan1z0825/nature-skills.git
cd nature-skills
mkdir -p ~/.codex/skills
cp -R skills/_shared ~/.codex/skills/
for d in skills/nature-*; do
  cp -R "$d" ~/.codex/skills/
done

```

--------------------------------

### Check scholaraio setup

Source: https://zimoliao.github.io/scholaraio/getting-started/installation

Check what is already configured. This is the most complete initial diagnostic surface, covering core and optional advanced items.

```bash
scholaraio setup check
```

--------------------------------

### fetch-pdf command examples

Source: https://zimoliao.github.io/scholaraio/guide/ingestion

Examples of using fetch-pdf to download PDFs from a DOI, publisher page, direct URL, or title. Options include --direct, --ingest, --out-dir, --paper, --all, and --force.

```bash
# Download a DOI, publisher landing page, direct PDF URL, or title to the configured paper inbox
scholaraio fetch-pdf 10.xxxx/example --direct

# Download and immediately run the normal ingest pipeline; the PDF is staged temporarily
scholaraio fetch-pdf 10.xxxx/example --direct --ingest

# Save the fetched PDF to a chosen directory; with --ingest, only that fetched file is ingested
scholaraio fetch-pdf 10.xxxx/example --direct --out-dir workspace/pdfs --ingest

# Refresh canonical PDFs for already ingested records
scholaraio fetch-pdf --paper <paper-id> --direct --force
scholaraio fetch-pdf --paper <paper-id-1> <paper-id-2> --direct --force
scholaraio fetch-pdf --all --direct --force

```

--------------------------------

### Start the WebUI with default settings

Source: https://zimoliao.github.io/scholaraio/guide/library-webui

Launches the ScholarAIO Library WebUI on the default address 127.0.0.1:8765 and opens the page in the browser. Use this command to start the local workspace for browsing records and running searches.

```bash
scholaraio gui

```

--------------------------------

### Example config.local.yaml

Source: https://zimoliao.github.io/scholaraio/getting-started/configuration

Shows the structure of config.local.yaml for setting API keys for LLM, ingest (mineru, s2), and Zotero. The mineru_api_key is a compatibility alias; MINERU_TOKEN is preferred. s2_api_key, zotero.api_key, and zotero.library_id are optional.

```yaml
llm:
  api_key: "sk-your-key-here"

ingest:
  mineru_api_key: "your-mineru-token"  # compatibility alias; MINERU_TOKEN is preferred
  s2_api_key: "your-semantic-scholar-key"  # optional

zotero:
  api_key: "your-zotero-key"  # optional
  library_id: "1234567"  # optional

```

--------------------------------

### Upgrade from 1.4 or 1.5: Source checkout install

Source: https://zimoliao.github.io/scholaraio/getting-started/upgrading-to-2.0

For a source checkout, replace the install command with these commands. The final command must be run from the ScholarAIO repository root.

```bash
git pull
pip install -e ".[full]"
```

--------------------------------

### Recommended migration path commands

Source: https://zimoliao.github.io/scholaraio/getting-started/upgrading-to-1.4

Commands to update the code/package, inspect runtime state, run the one-command offline migration, verify the journal, rebuild indexes, and run the setup diagnostic. Use a different --migration-id if you prefer a timestamped or machine-specific name.

```bash
# 1. Update the code/package.
git pull
pip install -e ".[full]"

# 2. Inspect the runtime state.
scholaraio migrate status

# 3. Run the one-command offline migration.
scholaraio migrate upgrade --migration-id upgrade-1.4.0 --confirm

# 4. Verify the journal.
scholaraio migrate verify --migration-id upgrade-1.4.0

# 5. Rebuild indexes after data lands in the fresh layout.
scholaraio index --rebuild

# 6. Run the normal setup diagnostic.
scholaraio setup check

```

--------------------------------

### Example ScholarAIO skill invocations

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

After installation, start a new Claude Code session in your target project. These slash-commands invoke ScholarAIO skills.

```text
/scholaraio:search
/scholaraio:show
/scholaraio:workspace

```

--------------------------------

### Upgrade from 2.0.0 Beta 1: Replace package explicitly

Source: https://zimoliao.github.io/scholaraio/getting-started/upgrading-to-2.0

When moving from the beta prerelease, replace the package explicitly because pip may consider the stable artifact equal to the installed beta. Then run pip check and setup check.

```bash
python -m pip install --force-reinstall --no-deps "scholaraio==2.0.0"
python -m pip check
scholaraio setup check
```

--------------------------------

### Install Graphviz and Inkscape on Ubuntu/Debian, macOS, and Conda

Source: https://zimoliao.github.io/scholaraio/writing-guide/graphviz-guide

Install Graphviz and Inkscape for SVG rendering. Use `sudo apt-get` on Ubuntu/Debian, `brew` on macOS, and `conda` for environment-specific installs. Verify with `dot -V` and `inkscape --version`.

```bash
# Ubuntu/Debian
sudo apt-get install graphviz inkscape

# macOS
brew install graphviz
brew install --cask inkscape

# Conda, useful when you only need dot/SVG rendering inside an env
conda install -c conda-forge graphviz

# Verify the commands that ScholarAIO and Beamer depend on
dot -V
inkscape --version

```

--------------------------------

### Set up agent integration

Source: https://zimoliao.github.io/scholaraio/getting-started/installation

Preview and apply agent integration to make the same ScholarAIO checkout available from other coding-agent projects.

```bash
scholaraio setup agent
scholaraio setup agent --apply
scholaraio setup agent check
```

--------------------------------

### Install ScholarAIO plugin in Claude Code

Source: https://zimoliao.github.io/scholaraio/getting-started/agent-setup

Run these commands inside Claude Code as slash-commands, not in your system shell. They add the ScholarAIO marketplace and install the plugin.

```text
/plugin marketplace add ZimoLiao/scholaraio
/plugin install scholaraio@scholaraio-marketplace

```

--------------------------------

### Install upstream Nature Skills bundle via Codex plugin

Source: https://zimoliao.github.io/scholaraio/guide/nature-workflow-quickstart

Adds the Nature Skills marketplace and installs the nature-skills plugin for direct upstream behavior in Codex.

```bash
codex plugin marketplace add https://github.com/Yuan1z0825/nature-skills --ref main
codex plugin add nature-skills@nature-skills

```

--------------------------------

### scholaraio toolref commands for end-to-end loop

Source: https://zimoliao.github.io/scholaraio/guide/toolref-onboarding

Commands to verify a new tool integration: fetch, list, show, and search. Run these in order to confirm the integration works end-to-end.

```bash
scholaraio toolref fetch <tool>
scholaraio toolref list <tool>
scholaraio toolref show <tool> <natural query>
scholaraio toolref search <tool> "<real query>"
```

--------------------------------

### Start the WebUI on a custom port without opening browser

Source: https://zimoliao.github.io/scholaraio/guide/library-webui

Starts the WebUI on port 9000 and prevents the browser from opening automatically. Use this when you need a different local port or prefer to access the page manually.

```bash
scholaraio gui --port 9000 --no-open

```

--------------------------------

### Commands to confirm fresh layout and rebuilt search index

Source: https://zimoliao.github.io/scholaraio/getting-started/upgrading-to-1.4

Real commands to confirm the fresh layout and rebuilt search index after migration: search, show, ws list, and explore list.

```bash
scholaraio search "your topic" --limit 5
scholaraio show "<paper-id>" --layer 2
scholaraio ws list
scholaraio explore list

```

--------------------------------

### Recommended split: config.yaml and config.local.yaml

Source: https://zimoliao.github.io/scholaraio/getting-started/configuration

Recommended configuration split: config.yaml holds non-secret target settings, while config.local.yaml holds the identity file and optional password. This keeps host-specific secrets out of the main config.

```yaml
# config.yaml
backup:
  source_dir: data
  targets:
    lab:
      host: 192.168.31.229
      user: lzmo
      path: /srv/scholaraio
      port: 1393
      scope: instance
      mode: default
      compress: true
      enabled: true

```

```yaml
# config.local.yaml
backup:
  targets:
    lab:
      identity_file: ~/.ssh/id_ed25519
      # password: your-ssh-password  # Optional fallback when the server does not accept your key

```
Tokens:
Raw