qiongli 0.12.1b1

Installer/upgrader CLI for qiongli (Codex / Claude Code / Gemini) without requiring a git fork.

qiongli

qiongli is the lightweight updater CLI for Qiongli (穷理), a contract-driven academic workflow system for Codex, Claude Code, and Gemini.

The full system name is Qiongli Zhengche (穷理证澈): Qiongli names the public research workflow, while Zhengche names the evidence-governance method that keeps claims, citations, assumptions, and output paths auditable.

What it does

• Install or refresh global qiongli-workflow skill assets
• Select the active subject package with --subject core|economics|accounting|economics-accounting
• Choose package coverage with --coverage complete|focused (complete is the default)
• Upgrade assets to newer upstream versions
• Support codex, claude, gemini, or all targets
• Run doctor checks before/after installation

Installation

For a global CLI command, pipx is recommended:

pipx install qiongli

Upgrade an existing PyPI install with:

pipx upgrade qiongli

You can also install with pip:

pip install qiongli

If you use pip inside an active virtual environment, the CLI is installed into that environment. That only affects where the Python command lives; it does not make the workflow assets project-local.

Global-first update model

Current releases separate the package install from workflow asset installation:

• pipx install qiongli / pipx upgrade qiongli updates the lightweight Python CLI.
• qiongli install --target all installs the default core/complete package.
• qiongli install --subject economics --target all installs the full framework plus economics specialization.
• qiongli install --subject accounting --target all installs the full framework plus accounting specialization.
• qiongli install --subject economics --coverage focused --target all installs the slimmer economics-focused package.
• qiongli install --subject economics-accounting --target all installs the official economics/accounting composite.
• qiongli upgrade --subject accounting --target all refreshes the active global qiongli-workflow skill assets for Codex, Claude Code, Gemini, and Antigravity.
• --project-dir is not required for normal global upgrades. It only selects a project when you run doctor, load project-level qiongli.toml / .qiongli.toml, or explicitly write project files with qiongli init / --parts project.

Global assets are written under client home directories such as:

~/.codex/skills/qiongli-workflow
~/.claude/skills/qiongli-workflow
~/.gemini/skills/qiongli-workflow

CLI

Main command and aliases:

• qiongli
• ql
• research-skills (legacy)
• rsk
• rsw

Check updates

qiongli check

Upgrade assets

qiongli install --target all
qiongli install --subject economics --target all
qiongli install --subject accounting --target all
qiongli install --subject economics --coverage focused --target all
qiongli install --subject economics-accounting --target all
qiongli upgrade --subject accounting --target all

Run doctor only when you want to check a specific project runtime:

qiongli upgrade --subject economics --target all --doctor --project-dir /path/to/project

The package includes a default upstream repo (jxpeng98/qiongli), so --repo is optional. Use --repo only when you want to override the default.

Override default repo (optional)

The CLI resolves upstream repo in this order:

1. --repo argument
2. QIONGLI_REPO environment variable
3. legacy RESEARCH_SKILLS_REPO environment variable
4. qiongli.toml or .qiongli.toml in your project path
5. Packaged default (qiongli/project.toml)

Option A: Global override

Add this to your shell profile (~/.zshrc, ~/.bashrc, etc.):

export QIONGLI_REPO="<owner>/<repo>"

Then reload shell:

source ~/.zshrc

Now you can run:

qiongli check
qiongli upgrade --subject core --target all

Option B: Project-level override

Create qiongli.toml in your project root:

[upstream]
repo = "jxpeng98/qiongli"
url = "https://github.com/<owner>/<repo>"

This keeps the override local to that project.

Typical usage

# Install or update the CLI from PyPI
pipx install qiongli
pipx upgrade qiongli

# Refresh global workflow assets
qiongli install --target all
qiongli install --subject economics --target all
qiongli install --subject accounting --target all
qiongli install --subject economics-accounting --target all

# Optional: initialize project-local files only when you want them
qiongli init --project-dir /path/to/project

--subject defaults to core and --coverage defaults to complete, so the default install is core/complete. With complete coverage, a specialized install keeps the full core framework and adds the requested subject overlays and subject-specific skills. --subject economics means economics/complete, not a reduced package. --subject accounting means accounting/complete, full framework plus accounting specialization. Use --coverage focused only when you deliberately want the slimmer selected subject package used by Desktop/Web ZIPs. Current official subjects are core, economics, accounting, and the named composite economics-accounting; composites are not arbitrary comma-separated stacking. Public Desktop ZIP subjects are core, economics, and economics-accounting, with no standalone accounting Desktop ZIP in this phase. Subject packages are specialized installs, not reduced-quality cuts; switching subjects or coverage is another install/upgrade with the new flags. Older installs without a SUBJECT_MANIFEST.json or SUBJECT marker are treated as legacy core / complete.

Create local customization scaffolds from a source checkout when you need generated output with local overlays:

qiongli customize --subject economics --name my-econ-lab --out ./qiongli-custom/econ-lab

Local customization is supported through the source materializer:

python3 scripts/materialize_subject_package.py \
  --subject economics \
  --coverage complete \
  --source . \
  --custom-dir /path/to/custom-qiongli \
  --out /tmp/qiongli-workflow

The custom directory can add local overlays, profiles, registry entries, and custom skill markdown for that generated output only. It does not modify the canonical source tree. qiongli customize plus --custom-dir materialization is for the Python/source checkout workflow; npm runtime installs use pre-generated payloads in this phase.

Links

• Repository: https://github.com/jxpeng98/qiongli
• Issues: https://github.com/jxpeng98/qiongli/issues