pubchem-cli 0.1.3 → 0.1.4

package/README.md

@@ -18,15 +18,30 @@ Global install:
 
 ```bash
 npm install -g pubchem-cli
+pubchem --help
 ```
 
-For local development in this repo:
+If you are hacking on this repository locally:
 
 ```bash
 go build -o ./pubchem ./cmd/pubchem
 ./pubchem --help
 ```
 
+## Mental Model
+
+Use the CLI in this order:
+
+1. Resolve an identifier to a record when you start from a name, CAS RN, InChIKey, or source ID.
+2. Use exact identity commands when you already have the CID, SID, or AID.
+3. Use search commands when you need candidate matches.
+4. Use `view` when you need headings and sections from PUG View.
+5. Use `raw` only when there is no higher-level verb yet.
+6. Use `export` when you need files.
+7. Use `batch` when you need many records.
+
+This CLI does not guess silently. That is intentional.
+
 ## Usage
 
 ```bash
@@ -38,8 +53,8 @@ Root flags:
 - `--json`: Output JSON to stdout.
 - `--plain`: Output stable plain text to stdout.
 - `--results-only`: In JSON mode, emit only the primary result.
-- `--select`: In JSON mode, select comma-separated fields with dot-path support.
-- `--force`: Skip confirmations for future destructive commands.
+- `--select`: In JSON mode, select comma-separated fields with exact dot-path support.
+- `--force`: Skip confirmations for future destructive commands and file overwrites.
 - `--no-input`: Never prompt; fail instead.
 - `--enable-commands`: Comma-separated list of enabled top-level commands.
 - `--version`: Print version and exit.
@@ -62,76 +77,472 @@ Top-level command families:
 - `agent`
 - `completion`
 
-## Examples
+## What To Use
+
+| Task | Command |
+|---|---|
+| Resolve a drug name, CAS RN, InChI, or InChIKey | `pubchem resolve compound ...` |
+| Exact compound lookup by CID | `pubchem identity compound ...` or `pubchem compound get ...` |
+| Similarity search around a known structure | `pubchem compound similar <cid> --query-type cid` |
+| Substructure or superstructure search | `pubchem compound substructure <cid> --query-type cid` or `pubchem compound superstructure <cid> --query-type cid` |
+| Resolve a substance by SID or depositor source ID | `pubchem resolve substance ...` or `pubchem substance sourceid ...` |
+| Search assays by gene, protein, name, source, or keyword | `pubchem assay search ...` |
+| PubMed, patents, and xrefs | `pubchem refs ...` |
+| Browse nested PUG View sections | `pubchem view ...` |
+| Fetch a raw endpoint that has no higher-level verb | `pubchem raw fetch ...` |
+| Export files or tabular data | `pubchem export ...` |
+| Repeat a workflow across many IDs | `pubchem batch ...` |
+| Discover exact flags and JSON shapes | `pubchem schema ...` |
+| Generate shell completion | `pubchem completion ...` |
+| Inspect stable exit codes | `pubchem agent exit-codes` |
+
+## Agent Playbook
 
-Version:
+If you are an agent, use this sequence:
+
+1. Start with `pubchem schema <command>` when you need the exact flag surface.
+2. Use `pubchem agent exit-codes` when you need a stable automation contract.
+3. Use `--json` by default.
+4. Add `--results-only` when the downstream consumer wants the primary payload only.
+5. Add `--select` only with exact field paths that already exist in the JSON output.
+6. Use `--enable-commands` when you need a restricted command allowlist.
+7. Prefer CID-based structure workflows over name-based structure workflows.
+
+## Resolve vs Identity
+
+Use `resolve` when the input is a name, registry number, InChIKey, or other identifier that may need normalization.
+
+Use `identity` when you already have the exact record ID and want the explicit no-guess form.
+
+Examples:
 
 ```bash
-$ pubchem --version
-pubchem dev
+pubchem identity compound 2244
+pubchem identity substance 92297672
+pubchem identity assay 541
 ```
 
-Compound search:
+## Compound Workflows
+
+Resolve a drug name to a CID:
 
 ```bash
-$ pubchem compound search aspirin --max 1
-{
-  "mode": "name",
-  "query": "aspirin",
-  "totalFound": 1,
-  "returned": 1,
-  "pageSize": 1,
-  "results": [
-    {
-      "cid": 2244,
-      "properties": {
-        "Charge": 0,
-        "Complexity": 212,
-        "ConnectivitySMILES": "CC(=O)OC1=CC=CC=C1C(=O)O",
-        "HBondAcceptorCount": 4,
-        "HBondDonorCount": 1,
-        "HeavyAtomCount": 13,
-        "IUPACName": "2-acetyloxybenzoic acid",
-        "InChIKey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
-        "MolecularFormula": "C9H8O4",
-        "MolecularWeight": "180.16",
-        "RotatableBondCount": 3,
-        "SMILES": "CC(=O)OC1=CC=CC=C1C(=O)O",
-        "TPSA": 63.6,
-        "XLogP": 1.2
-      }
+pubchem resolve compound imatinib --json --results-only --max 1
+```
+
+Sample output:
+
+```json
+[
+  {
+    "cid": 5291,
+    "properties": {
+      "InChIKey": "KTUFNOKKBVMGRW-UHFFFAOYSA-N",
+      "MolecularFormula": "C29H31N7O",
+      "MolecularWeight": "493.6"
     }
-  ]
-}
+  }
+]
+```
+
+When you already know the CID, use exact identity:
+
+```bash
+pubchem identity compound 2244 --json
+```
+
+Get compound details and common pharma fields:
+
+```bash
+pubchem compound get 2244 --synonyms --description --classification --drug-likeness --json
+```
+
+Pull a compact property panel:
+
+```bash
+pubchem compound properties 2244 --json --results-only --select=cid,properties.MolecularFormula
+```
+
+Sample output:
+
+```json
+[
+  {
+    "cid": 2244,
+    "properties.MolecularFormula": "C9H8O4"
+  }
+]
+```
+
+Search compounds by name:
+
+```bash
+pubchem compound search aspirin --max 1
+```
+
+Search compounds by formula:
+
+```bash
+pubchem compound search C9H8O4 --mode formula --allow-other-elements --max 10
+```
+
+Run SAR-style similarity search from a CID:
+
+```bash
+pubchem compound similar 5291 --query-type cid --threshold 90 --max 20
+```
+
+Run structure searches from a CID:
+
+```bash
+pubchem compound substructure 5291 --query-type cid --max 20
+pubchem compound superstructure 5291 --query-type cid --max 20
+```
+
+Important rule:
+
+- Do not feed a plain drug name directly into `compound similar`, `compound substructure`, or `compound superstructure` and expect the CLI to guess.
+- If you start from a name, run `pubchem resolve compound <name>` first, then feed the resulting CID into the structure search.
+- This is the deterministic, agent-safe path.
+
+Name-to-SAR recipe:
+
+```bash
+pubchem resolve compound imatinib --json --results-only --select=cid --max 1
+pubchem compound similar <cid> --query-type cid --max 20
+```
+
+Structure files and metadata:
+
+```bash
+pubchem compound structure 2244 --record-type 3d --format json
+pubchem compound structure 2244 --record-type 3d --format sdf --out aspirin-3d.sdf
+pubchem compound structure 2244 --record-type 2d --format mol --out aspirin-2d.mol
+```
+
+Compound images:
+
+```bash
+pubchem compound image 2244 --inline --json
+pubchem compound image 2244 --out aspirin.png --force
+```
+
+Compound xrefs and safety:
+
+```bash
+pubchem compound xref 2244
+pubchem compound safety 2244
+```
+
+## Substance Workflows
+
+Resolve a substance by SID:
+
+```bash
+pubchem resolve substance 92297672 --json
+```
+
+Search substances by name:
+
+```bash
+pubchem substance search aspirin --max 20
+```
+
+Search substances by depositor source and source ID:
+
+```bash
+pubchem substance sourceid ChemIDplus 0002153982 --max 20
+```
+
+Search substances by registry xref:
+
+```bash
+pubchem substance search D41527A7-A9EB-472D-A7FC-312821130549 --mode xref --xref-type RegistryID
+```
+
+Map substance records to compounds:
+
+```bash
+pubchem substance cids 92297672
+```
+
+Fetch substance xrefs for registry normalization:
+
+```bash
+pubchem substance xref 92297672 --types RegistryID,DBURL,SBURL
+```
+
+Batch substance workflows:
+
+```bash
+pubchem batch substance cids 92297672 135052148 --progress
+pubchem batch substance xref 92297672 135052148 --types RegistryID,DBURL,SBURL --progress
+```
+
+## Assay Workflows
+
+Resolve an assay by AID or by target/name:
+
+```bash
+pubchem resolve assay 541 --json
+pubchem resolve assay EGFR --mode target --target-type genesymbol --json
+```
+
+Search assays:
+
+```bash
+pubchem assay search EGFR --mode target --target-type genesymbol --max 20
+pubchem assay search viability --mode name --max 20
+pubchem assay search ncgc --mode source --max 20
+pubchem assay search kinase --mode keyword --max 20
+```
+
+Fetch assay details and concise result tables:
+
+```bash
+pubchem assay get 541
+pubchem assay results 541 --outcome active --max 20
+```
+
+Batch assay workflows:
+
+```bash
+pubchem batch assay get 541 542 --progress
+pubchem batch assay results 541 542 --outcome active --progress
+```
+
+## References, Literature, and Patents
+
+Search PubMed:
+
+```bash
+pubchem refs search aspirin --max 20
+```
+
+Fetch PubMed metadata by PMID:
+
+```bash
+pubchem refs get 22385 --json --results-only --select=url
+```
+
+Sample output:
+
+```json
+[
+  {
+    "url": "https://pubmed.ncbi.nlm.nih.gov/22385/"
+  }
+]
+```
+
+Pull compound-linked literature:
+
+```bash
+pubchem refs literature compound 2244 --max 20
+```
+
+Pull compound-linked patents:
+
+```bash
+pubchem refs patents compound 2244 --max 20
+```
+
+Pull compound and substance xrefs through the reference surface:
+
+```bash
+pubchem refs external compound 2244
+pubchem refs external substance 92297672
+```
+
+When you need a bibliography or patent landscape, prefer `refs` over raw PubMed scraping. It already normalizes the citation records.
+
+## PUG View Browsing
+
+Use `view` when you want headings and sections, not just raw IDs.
+
+Get or browse a compound record:
+
+```bash
+pubchem view get compound 2244
+pubchem view browse compound 2244
 ```
 
-3D structure metadata:
+Search inside a compound record:
 
 ```bash
-$ pubchem compound structure 2244 --record-type 3d --format json
+pubchem view search compound 2244 Safety --json --max 1
+```
+
+Sample output:
+
+```json
 {
-  "recordType": "3d",
-  "downloadUrl": "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/cid/2244/SDF?record_type=3d",
+  "entityType": "compound",
+  "identifier": "2244",
+  "query": "Safety",
+  "totalFound": 20,
+  "pageSize": 1,
+  "truncated": true,
   "results": [
     {
-      "cid": 2244,
-      "structure": {
-        "title": "Aspirin",
-        "molecularFormula": "C9H8O4",
-        "molecularWeight": 180.16,
-        "inchiKey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
-        "has3d": true
-      }
+      "path": "Chemical and Physical Properties",
+      "tocHeading": "Chemical and Physical Properties",
+      "description": "Various chemical and physical properties that are experimentally determined for this compound."
     }
   ]
 }
 ```
 
-For the full command tree and machine-readable schema, use:
+Browse specific sections:
 
 ```bash
-pubchem --help
-pubchem schema
+pubchem view section compound 2244 --heading "Safety and Hazards"
+pubchem view section compound 2244 --heading "Names and Identifiers"
+```
+
+The same patterns work for substances and assays.
+
+## Raw Escape Hatch
+
+Use `raw fetch` only when the CLI does not yet have a dedicated verb.
+
+```bash
+pubchem raw fetch pug /compound/cid/2244/JSON
+pubchem raw fetch view /data/compound/2244/JSON
+pubchem raw fetch pubmed /esummary.fcgi?db=pubmed&id=22385&retmode=json
+```
+
+You can also pass an allowed full URL, but only for PubChem and NCBI hosts.
+
+## Exports
+
+Export compound structures:
+
+```bash
+pubchem export compound structure 2244 --format smiles
+pubchem export compound structure 2244 --record-type 3d --format sdf --out aspirin-3d.sdf
+pubchem export compound structure 2244 --record-type 2d --format mol --out aspirin-2d.mol
+```
+
+Export compound properties:
+
+```bash
+pubchem export compound properties 2244 5291 --properties MolecularFormula,MolecularWeight --format tsv --out compounds.tsv
+```
+
+Export assay results:
+
+```bash
+pubchem export assay results 541 --outcome active --format csv --out assay-results.csv
+```
+
+## Batch Automation
+
+Use `batch` when you have multiple IDs and want one command to do the same work repeatedly.
+
+```bash
+pubchem batch compound get 2244 5291 --progress
+pubchem batch compound properties 2244 5291 --properties MolecularFormula,MolecularWeight --progress
+pubchem batch compound bioactivity 2244 5291 --outcome active --progress
+pubchem batch compound xref 2244 5291 --progress
+```
+
+Progress goes to stderr so stdout stays machine-readable.
+
+## Selection and JSON Shape
+
+`--select` is exact-path only. There is no fuzzy matching.
+
+Good examples:
+
+```bash
+pubchem compound search aspirin --json --results-only --select=cid,properties.MolecularFormula --max 1
+pubchem refs get 22385 --json --results-only --select=url
+pubchem substance search aspirin --json --results-only --select=sid --max 1
+```
+
+If you need a nested field, use the exact path that appears in the JSON output.
+
+## Exit Codes
+
+Use `pubchem agent exit-codes` for automation.
+
+The current stable codes are:
+
+- `0` success
+- `1` generic error
+- `2` usage error
+- `3` not found
+- `4` timeout
+- `5` command disabled by `--enable-commands`
+
+## Shell Completion
+
+```bash
+pubchem completion bash
+pubchem completion zsh
+pubchem completion fish
+pubchem completion powershell
+```
+
+## Common Limits and Good Practice
+
+- Prefer CID-based structure workflows whenever you can.
+- If you start from a name, resolve first and reuse the CID.
+- Broad SMILES similarity and substructure searches can still fail or time out upstream at PubChem.
+- The CLI now reports those failures cleanly instead of hiding them behind parser noise.
+- `raw fetch` is intentionally allowlisted; it is an escape hatch, not a free-for-all.
+- Use `schema` instead of guessing flags.
+
+## Sample Command Set For Agents
+
+If you want a small, practical agent allowlist:
+
+```bash
+pubchem --enable-commands compound,substance,assay,refs,view,raw,resolve,identity,batch,export,schema,agent,completion compound search aspirin --max 1
+```
+
+That style keeps the command surface predictable while still covering most PubChem work.
+
+## More Examples
+
+Find a structure, then inspect it, then export a file:
+
+```bash
+pubchem resolve compound imatinib --json --results-only --max 1
+pubchem compound get 5291 --synonyms --classification --json
+pubchem export compound structure 5291 --record-type 3d --format sdf --out imatinib-3d.sdf
+```
+
+Trace a compound into the literature:
+
+```bash
+pubchem refs literature compound 5291 --max 20
+pubchem refs patents compound 5291 --max 20
+```
+
+Move from an assay target to a hit list:
+
+```bash
+pubchem assay search EGFR --mode target --target-type genesymbol --max 20
+pubchem assay results 3364 --outcome active --max 20
+```
+
+Inspect a PubChem record tree and then pull only one section:
+
+```bash
+pubchem view search compound 2244 Hazard --max 5
+pubchem view section compound 2244 --heading "Safety and Hazards"
+```
+
+## For New Users
+
+If you only remember three commands, remember these:
+
+```bash
+pubchem resolve compound aspirin
+pubchem compound get 2244
+pubchem view search compound 2244 Safety
 ```
 
-If you want the exact command and flag surface for automation, prefer `pubchem schema <command>` and `pubchem --help` over guessing from memory.
+Everything else in the CLI builds from those patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pubchem-cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "PubChem in your terminal.",
   "repository": {
     "type": "git",