Cli And Indexing

---
name: cli-and-indexing
description: "Operate the PaperQA pqa CLI and local full-text index workflows safely."
disable-model-invocation: true
metadata:
  disco-role: operating
license: Apache 2.0
---

# PaperQA CLI and Indexing

Use this sub-skill when the task is about the `pqa` command-line interface or
PaperQA's local search indexes: `pqa ask`, `pqa search`, `pqa index`, `pqa view`,
`pqa save`, `--settings`, `--index`, `PQA_HOME`, manifest CSVs, named indexes,
autogenerated indexes, answer history search, and index reuse or invalidation.

Do not use this sub-skill for Python `Docs`/`ask`/`agent_query` RAG code,
parser internals, metadata-provider APIs, or deep model/provider settings. Route
those to the sibling sub-skills for agentic RAG, docs/parsing, metadata/sources,
and settings/configuration.

## Operating rules

1. For CLI syntax and safe examples, read
   [references/cli-reference.md](references/cli-reference.md).
2. For index names, directories, manifests, reuse, answer indexes, recursive
   scanning, and invalidation, read
   [references/indexing-workflows.md](references/indexing-workflows.md).
3. For failures or surprising behavior, read
   [references/troubleshooting.md](references/troubleshooting.md).
4. Use [scripts/inspect_cli.py](scripts/inspect_cli.py) before relying on a
   user's environment-specific `pqa` entry point or parser behavior. It only
   inspects help text and does not run queries, embeddings, or metadata lookups.
5. Use [scripts/validate_manifest.py](scripts/validate_manifest.py) before an
   index build that depends on a manifest CSV.

## Safety boundary

`pqa ask` and `pqa index` can call LLM, embedding, and paper-metadata providers
while parsing, indexing, searching, or answering unless the user configured
local/fake/offline-compatible settings. Before running those commands, make the
provider, credential, network, cost, and rate-limit implications explicit.
Prefer `pqa view`, `pqa search` on an existing index, `inspect_cli.py`, and
`validate_manifest.py` for dry-run or diagnostic steps.

## Quick routing map

- Need to view or save named CLI settings: use `pqa view` / `pqa save`, then
  cross-route provider details to `../settings-and-configuration/SKILL.md`.
- Need to build or reuse a local paper index: use this sub-skill's indexing
  workflows and keep document paths user-owned.
- Need full-text search over a prebuilt paper index or previous answers: use
  `pqa search` with the correct `--index` and `--agent.index.index_directory`.
- Need generated answers with citations from local documents: this sub-skill
  covers the CLI command shape; route answer behavior and Python API details to
  `../agentic-rag/SKILL.md`.
- Need file-format parsing or custom file filtering beyond CLI flags: route to
  `../docs-and-parsing/SKILL.md`.