---

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.
2. For index names, directories, manifests, reuse, answer indexes, recursive scanning, and invalidation, read references/indexing-workflows.md.
3. For failures or surprising behavior, read references/troubleshooting.md.
4. Use 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 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.