datalegion-cli 1.7.0__tar.gz → 1.8.0__tar.gz

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: datalegion-cli
-Version: 1.7.0
+Version: 1.8.0
 Summary: CLI for the Data Legion API — agent-friendly, fully async
 Project-URL: Homepage, https://www.datalegion.ai
 Project-URL: Documentation, https://www.datalegion.ai/docs
@@ -62,7 +62,7 @@ datalegion-cli person enrich --email john@example.com
 brew install datalegion-ai/tap/datalegion-cli
 ```
 
-### From PyPI (or private index)
+### From PyPI (or Private Index)
 
 ```bash
 uv pip install datalegion-cli
@@ -80,7 +80,7 @@ To install from a private index:
 uv pip install datalegion-cli --extra-index-url https://your-private-index.com/simple
 ```
 
-### From GitHub release
+### From GitHub Release
 
 Download the `.whl` from the [latest release](https://github.com/datalegion-ai/datalegion-cli/releases/latest) and install:
 
@@ -88,7 +88,7 @@ Download the `.whl` from the [latest release](https://github.com/datalegion-ai/d
 uv pip install datalegion_cli-*.whl
 ```
 
-### From source
+### From Source
 
 ```bash
 git clone https://github.com/datalegion-ai/datalegion-cli.git
@@ -120,7 +120,7 @@ Or via environment variable (takes precedence over file config):
 export LEGION_API_KEY=legion_your_key_here
 ```
 
-### Other config options
+### Other Config Options
 
 ```bash
 # Set the API base URL
@@ -138,7 +138,7 @@ datalegion-cli config path
 
 Config is stored at `~/.datalegion/config.toml`. Override the location with `LEGION_CONFIG_DIR`.
 
-### Install method detection
+### Install Method Detection
 
 The `update` command auto-detects how the CLI was installed:
 
@@ -153,7 +153,7 @@ You can override detection by setting `install_method` in config. For pip instal
 
 ## Usage
 
-### Person enrichment
+### Person Enrichment
 
 ```bash
 # By email
@@ -165,28 +165,35 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 # By LinkedIn
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
-# Multiple results with minimum confidence
+# Minimum confidence
 datalegion-cli person enrich --email john@example.com --min-confidence high
 
 # Select specific fields
 datalegion-cli person enrich --email john@example.com --fields "full_name,emails,phones"
 ```
 
-### Person search (Beta)
+### Person Search
 
 ```bash
 # SQL-based search
 datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
 ```
 
-### Person discovery (Beta)
+`query` can also be an Elasticsearch-style query object as JSON (`bool`, `term`, `terms`, `match`, `match_phrase`, `range`, `exists`, `prefix`, `wildcard`, `nested`), on the response's own field names. For deep paging, pass each page's `next_cursor` back with `--cursor`; the last page has none. Company search takes both too.
+
+```bash
+datalegion-cli person search '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100
+datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor "<next_cursor from the last page>"
+```
+
+### Person Discovery (Beta)
 
 ```bash
 # Natural-language search
 datalegion-cli person discover "software engineers in San Francisco who know Rust" --limit 10
 ```
 
-### Company enrichment
+### Company Enrichment
 
 ```bash
 # By domain
@@ -199,21 +206,21 @@ datalegion-cli company enrich --ticker AAPL
 datalegion-cli company enrich --name "Stripe" --industry "Financial Services"
 ```
 
-### Company search (Beta)
+### Company Search
 
 ```bash
 # SQL-based search
 datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
 ```
 
-### Company discovery (Beta)
+### Company Discovery (Beta)
 
 ```bash
 # Natural-language search
 datalegion-cli company discover "fintech startups in New York with under 50 employees"
 ```
 
-### Utility commands
+### Utility Commands
 
 ```bash
 # Clean and normalize fields
@@ -240,7 +247,7 @@ datalegion-cli credits balance
 datalegion-cli credits usage --from 2026-01-01 --to 2026-03-01
 ```
 
-### Other commands
+### Other Commands
 
 ```bash
 # Check for updates
@@ -253,7 +260,7 @@ datalegion-cli update
 datalegion-cli version
 ```
 
-## Agent / automation usage
+## Agent / Automation Usage
 
 The CLI is designed to be called by AI agents and scripts. Key patterns:
 
@@ -274,13 +281,13 @@ datalegion-cli person enrich --email bad 2>/dev/null
 
 ## Sandbox
 
-Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, bulk enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes Enrich, Bulk Enrich, Search and Discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
 
 ```bash
 datalegion-cli --sandbox person enrich --email anyone@example.com
 ```
 
-## Global flags
+## Global Flags
 
 | Flag | Description |
 |------|-------------|

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/README.md

@@ -27,7 +27,7 @@ datalegion-cli person enrich --email john@example.com
 brew install datalegion-ai/tap/datalegion-cli
 ```
 
-### From PyPI (or private index)
+### From PyPI (or Private Index)
 
 ```bash
 uv pip install datalegion-cli
@@ -45,7 +45,7 @@ To install from a private index:
 uv pip install datalegion-cli --extra-index-url https://your-private-index.com/simple
 ```
 
-### From GitHub release
+### From GitHub Release
 
 Download the `.whl` from the [latest release](https://github.com/datalegion-ai/datalegion-cli/releases/latest) and install:
 
@@ -53,7 +53,7 @@ Download the `.whl` from the [latest release](https://github.com/datalegion-ai/d
 uv pip install datalegion_cli-*.whl
 ```
 
-### From source
+### From Source
 
 ```bash
 git clone https://github.com/datalegion-ai/datalegion-cli.git
@@ -85,7 +85,7 @@ Or via environment variable (takes precedence over file config):
 export LEGION_API_KEY=legion_your_key_here
 ```
 
-### Other config options
+### Other Config Options
 
 ```bash
 # Set the API base URL
@@ -103,7 +103,7 @@ datalegion-cli config path
 
 Config is stored at `~/.datalegion/config.toml`. Override the location with `LEGION_CONFIG_DIR`.
 
-### Install method detection
+### Install Method Detection
 
 The `update` command auto-detects how the CLI was installed:
 
@@ -118,7 +118,7 @@ You can override detection by setting `install_method` in config. For pip instal
 
 ## Usage
 
-### Person enrichment
+### Person Enrichment
 
 ```bash
 # By email
@@ -130,28 +130,35 @@ datalegion-cli person enrich --name "Jane Smith" --company "Acme Corp" --city "N
 # By LinkedIn
 datalegion-cli person enrich --social-url "https://linkedin.com/in/johndoe"
 
-# Multiple results with minimum confidence
+# Minimum confidence
 datalegion-cli person enrich --email john@example.com --min-confidence high
 
 # Select specific fields
 datalegion-cli person enrich --email john@example.com --fields "full_name,emails,phones"
 ```
 
-### Person search (Beta)
+### Person Search
 
 ```bash
 # SQL-based search
 datalegion-cli person search "SELECT * FROM people WHERE company_name ILIKE '%google%' AND state = 'CA'" --limit 5
 ```
 
-### Person discovery (Beta)
+`query` can also be an Elasticsearch-style query object as JSON (`bool`, `term`, `terms`, `match`, `match_phrase`, `range`, `exists`, `prefix`, `wildcard`, `nested`), on the response's own field names. For deep paging, pass each page's `next_cursor` back with `--cursor`; the last page has none. Company search takes both too.
+
+```bash
+datalegion-cli person search '{"bool": {"filter": [{"term": {"company_name": "google"}}, {"match": {"job_title": "engineer"}}]}}' --limit 100
+datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor "<next_cursor from the last page>"
+```
+
+### Person Discovery (Beta)
 
 ```bash
 # Natural-language search
 datalegion-cli person discover "software engineers in San Francisco who know Rust" --limit 10
 ```
 
-### Company enrichment
+### Company Enrichment
 
 ```bash
 # By domain
@@ -164,21 +171,21 @@ datalegion-cli company enrich --ticker AAPL
 datalegion-cli company enrich --name "Stripe" --industry "Financial Services"
 ```
 
-### Company search (Beta)
+### Company Search
 
 ```bash
 # SQL-based search
 datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
 ```
 
-### Company discovery (Beta)
+### Company Discovery (Beta)
 
 ```bash
 # Natural-language search
 datalegion-cli company discover "fintech startups in New York with under 50 employees"
 ```
 
-### Utility commands
+### Utility Commands
 
 ```bash
 # Clean and normalize fields
@@ -205,7 +212,7 @@ datalegion-cli credits balance
 datalegion-cli credits usage --from 2026-01-01 --to 2026-03-01
 ```
 
-### Other commands
+### Other Commands
 
 ```bash
 # Check for updates
@@ -218,7 +225,7 @@ datalegion-cli update
 datalegion-cli version
 ```
 
-## Agent / automation usage
+## Agent / Automation Usage
 
 The CLI is designed to be called by AI agents and scripts. Key patterns:
 
@@ -239,13 +246,13 @@ datalegion-cli person enrich --email bad 2>/dev/null
 
 ## Sandbox
 
-Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes enrich, bulk enrich, search and discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
+Try commands without spending credits: `--sandbox` (or `LEGION_SANDBOX=1`, or `datalegion-cli config set sandbox true`) makes Enrich, Bulk Enrich, Search and Discover return sample records with every field a real record has. Utilities, which are free, still call the real API. Sandbox discover answers only a few fixed example queries.
 
 ```bash
 datalegion-cli --sandbox person enrich --email anyone@example.com
 ```
 
-## Global flags
+## Global Flags
 
 | Flag | Description |
 |------|-------------|

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "datalegion-cli"
-version = "1.7.0"
+version = "1.8.0"
 description = "CLI for the Data Legion API — agent-friendly, fully async"
 readme = "README.md"
 requires-python = ">=3.11"

datalegion_cli-1.8.0/src/datalegion_cli/commands/__init__.py

@@ -0,0 +1,26 @@
+"""CLI command modules."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Any
+
+import typer
+
+CursorOpt = Annotated[
+    str | None,
+    typer.Option(
+        "--cursor",
+        help="The previous page's next_cursor, for deep paging (instead of an offset).",
+    ),
+]
+
+
+def search_query(text: str) -> str | dict[str, Any]:
+    """SQL as given, or a query object when the argument is a JSON object."""
+    if not text.lstrip().startswith("{"):
+        return text
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        raise typer.BadParameter(f"The query looks like JSON but doesn't parse: {e.msg}.") from e

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/src/datalegion_cli/commands/company.py

@@ -10,6 +10,7 @@ import typer
 
 from datalegion_cli.async_typer import async_command
 from datalegion_cli.client import APIError, LegionClient
+from datalegion_cli.commands import CursorOpt, search_query
 from datalegion_cli.output import emit_credits, emit_error, emit_json, emit_search_warning
 
 app = typer.Typer(name="company", help="Company enrichment, search, and discovery.")
@@ -102,24 +103,33 @@ async def enrich(
 @app.command()
 @async_command
 async def search(
-    query: Annotated[str, typer.Argument(help="SQL SELECT query against the companies table.")],
+    query: Annotated[
+        str,
+        typer.Argument(
+            help="SQL SELECT query against the companies table, or a query object as JSON."
+        ),
+    ],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
 ) -> None:
-    """Search for companies with a SQL SELECT over the companies table, no LIMIT (Beta).
+    """Search for companies with a SQL SELECT over the companies table, no LIMIT.
 
     Examples:
         datalegion-cli company search "SELECT * FROM companies WHERE industry ILIKE '%software%' AND legion_employee_count > 100"
         datalegion-cli company search "SELECT * FROM companies WHERE name ILIKE '%tech%'" --limit 20
         datalegion-cli company search "SELECT * FROM companies WHERE domain = 'stripe.com'" --fields "name,domain,industry"
+        datalegion-cli company search '{"term": {"domain": "stripe.com"}}'
+        datalegion-cli company search "SELECT * FROM companies WHERE industry = 'banking'" --limit 100 --cursor <next_cursor>
     """
     client = LegionClient()
     try:
         result = await client.company_search(
-            query=query,
+            query=search_query(query),
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/src/datalegion_cli/commands/person.py

@@ -10,6 +10,7 @@ import typer
 
 from datalegion_cli.async_typer import async_command
 from datalegion_cli.client import APIError, LegionClient
+from datalegion_cli.commands import CursorOpt, search_query
 from datalegion_cli.output import emit_credits, emit_error, emit_json, emit_search_warning
 
 app = typer.Typer(name="person", help="Person enrichment, search, and discovery.")
@@ -128,23 +129,32 @@ async def enrich(
 @app.command()
 @async_command
 async def search(
-    query: Annotated[str, typer.Argument(help="SQL SELECT query against the people table.")],
+    query: Annotated[
+        str,
+        typer.Argument(
+            help="SQL SELECT query against the people table, or a query object as JSON."
+        ),
+    ],
     limit: LimitOpt = 1,
+    cursor: CursorOpt = None,
     titlecase: TitleOpt = False,
     include_fields: FieldsInclude = None,
     exclude_fields: FieldsExclude = None,
 ) -> None:
-    """Search for people with a SQL SELECT over the people table, no LIMIT (Beta).
+    """Search for people with a SQL SELECT over the people table, no LIMIT.
 
     Examples:
         datalegion-cli person search "SELECT * FROM people WHERE job_title = 'ceo' AND company_name ILIKE '%acme%'"
         datalegion-cli person search "SELECT * FROM people WHERE city = 'san francisco'" --limit 20
+        datalegion-cli person search '{"term": {"company_name": "acme"}}' --limit 100
+        datalegion-cli person search "SELECT * FROM people WHERE state = 'ohio'" --limit 100 --cursor <next_cursor>
     """
     client = LegionClient()
     try:
         result = await client.person_search(
-            query=query,
+            query=search_query(query),
             limit=limit,
+            cursor=cursor,
             titlecase=titlecase,
             include_fields=include_fields,
             exclude_fields=exclude_fields,

{datalegion_cli-1.7.0 → datalegion_cli-1.8.0}/tests/test_commands.py

@@ -168,6 +168,36 @@ class TestPersonSearch:
         assert result.exit_code == 0
 
 
+class TestSearchQueryObjectAndCursor:
+    @pytest.mark.parametrize("entity", ["person", "company"])
+    def test_a_json_query_goes_as_an_object_with_the_cursor(self, monkeypatch, entity):
+        _mock_config(monkeypatch)
+        sent = []
+
+        async def fake_request(self, method, endpoint, *, payload=None, params=None):
+            sent.append(payload)
+            return {"matches": [], "total": 0, "next_cursor": "abc"}
+
+        monkeypatch.setattr("datalegion_cli.client.LegionClient.request", fake_request)
+        result = runner.invoke(
+            app, [entity, "search", '{"exists": {"field": "legion_id"}}', "--cursor", "abc"]
+        )
+        assert result.exit_code == 0, result.output
+        assert sent[0]["query"] == {"exists": {"field": "legion_id"}}
+        assert sent[0]["cursor"] == "abc"
+        assert json.loads(result.stdout)["next_cursor"] == "abc"
+
+    def test_a_query_that_looks_like_json_but_does_not_parse_is_refused(self, monkeypatch):
+        _mock_config(monkeypatch)
+        result = runner.invoke(app, ["person", "search", "{not json"])
+        assert result.exit_code == 2
+
+    def test_sql_stays_a_string(self):
+        from datalegion_cli.commands import search_query
+
+        assert search_query("SELECT * FROM people") == "SELECT * FROM people"
+
+
 class TestPersonDiscover:
     def test_discover(self, monkeypatch):
         _mock_config(monkeypatch)

datalegion_cli-1.7.0/src/datalegion_cli/commands/__init__.py

@@ -1 +0,0 @@
-"""CLI command modules."""