feat(cli): add --from-pageindex-cloud flag to add command

Author: KylinMountain

openkb/cli.py

@@ -689,23 +689,44 @@ def init(model, language):
 
 
 @cli.command()
-@click.argument("path")
+@click.argument("path", required=False)
+@click.option(
+    "--from-pageindex-cloud", "from_pageindex_cloud", default=None, metavar="DOC_ID",
+    help="Import an already-indexed PageIndex Cloud document by its doc-id "
+         "(no local file). Mutually exclusive with PATH.",
+)
 @click.pass_context
 @_with_kb_lock(exclusive=True)
-def add(ctx, path):
+def add(ctx, path, from_pageindex_cloud):
     """Add a document or directory of documents at PATH to the knowledge base.
 
     PATH may be a local file, a local directory (which is walked
     recursively for supported extensions), or an http(s) URL. URLs are
     fetched into ``raw/`` first: PDF responses (by Content-Type and
     magic-byte sniff) are saved as ``.pdf``; HTML responses are run
     through trafilatura's main-content extractor and saved as ``.md``.
+
+    Alternatively, pass --from-pageindex-cloud <DOC_ID> to import a document
+    that is already indexed in PageIndex Cloud, with no local file. Requires
+    the PAGEINDEX_API_KEY environment variable.
     """
     kb_dir = _find_kb_dir(ctx.obj.get("kb_dir_override"))
     if kb_dir is None:
         click.echo("No knowledge base found. Run `openkb init` first.")
         return
 
+    # Cloud import path — mutually exclusive with a local/URL PATH.
+    if from_pageindex_cloud is not None:
+        if path is not None:
+            click.echo("Provide either PATH or --from-pageindex-cloud, not both.")
+            return
+        import_from_pageindex_cloud(from_pageindex_cloud, kb_dir)
+        return
+
+    if path is None:
+        click.echo("Provide a PATH or use --from-pageindex-cloud <DOC_ID>.")
+        return
+
     # URL ingest: download into raw/ first, then call add_single_file
     # explicitly so we can clean up the just-downloaded file if it
     # turns out to be a duplicate (registry already has its hash).

tests/test_add_command.py

@@ -204,6 +204,34 @@ def test_add_oldest_legacy_entry_converges_to_single_entry(self, tmp_path):
         assert len(new_entries) == 1             # …exactly one entry survives
         assert new_entries[0]["path"]            # with path identity persisted
 
+    def test_add_from_pageindex_cloud_dispatches(self, tmp_path):
+        kb_dir = self._setup_kb(tmp_path)
+        runner = CliRunner()
+        with patch("openkb.cli.import_from_pageindex_cloud", return_value="added") as mock_imp, \
+             patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            runner.invoke(cli, ["add", "--from-pageindex-cloud", "doc-123"])
+            mock_imp.assert_called_once_with("doc-123", kb_dir)
+
+    def test_add_rejects_path_and_cloud_together(self, tmp_path):
+        kb_dir = self._setup_kb(tmp_path)
+        doc = tmp_path / "test.md"
+        doc.write_text("# Hi")
+        runner = CliRunner()
+        with patch("openkb.cli.import_from_pageindex_cloud") as mock_imp, \
+             patch("openkb.cli.add_single_file") as mock_add, \
+             patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            result = runner.invoke(cli, ["add", str(doc), "--from-pageindex-cloud", "doc-1"])
+            assert "not both" in result.output
+            mock_imp.assert_not_called()
+            mock_add.assert_not_called()
+
+    def test_add_requires_path_or_cloud(self, tmp_path):
+        kb_dir = self._setup_kb(tmp_path)
+        runner = CliRunner()
+        with patch("openkb.cli._find_kb_dir", return_value=kb_dir):
+            result = runner.invoke(cli, ["add"])
+            assert "Provide a PATH" in result.output
+
 
 class TestImportFromPageindexCloud:
     def _setup_kb(self, tmp_path):