sv-cli 0.3.0__tar.gz → 0.5.0__tar.gz

{sv_cli-0.3.0 → sv_cli-0.5.0}/AGENT.md

@@ -55,16 +55,16 @@ All 16 available tools. Use exact command names — aliases are human shortcuts.
 
 | Command | Alias | Default Action | API Required Fields | Async |
 |---|---|---|---|---|
-| `better-keywords` | `keywords` | `research` / `filter` | `--keyword` (`filter` also needs `--data`) | No |
+| `better-keywords` | `keywords` | `research` / `filter` | `--keyword` (`filter` needs a JSON `data` array — raw call only) | No |
 | `content-transformer` | `transform` | `rewrite` | `--text` | No |
 | `core-analysis` | `core` | `analyze` | *(none required)* | No |
 | `geo-audit` | `audit` | `create-task` | `--url` `--keyword` | Yes |
 | `insight-igniter` | `insights` | `entities` | `--url` | No |
 | `preliminary-audit` | `prelim-audit` | `analyze` | `--url` | No |
-| `ranklens` | — | `rank` | `--keyword` `--url` | No |
+| `ranklens` | — | `rank` | `--entity` `--url` | No |
 | `seo-image` | `image` | `generate` | `--keyword` | No |
 | `seogpt` | `seo-gpt` | `generate` | `--keyword` `--type` | No |
-| `seogpt2` | `seo-gpt2` | `create-task` | `--keyword` *(= Topic)* | Yes |
+| `seogpt2` | `seo-gpt2` | `create-task` | `--topic` *(`--keyword`/`--kw` is a separate, optional field)* | Yes |
 | `seogpt-compare` | `compare` | `create-task` | `--url` `--keyword` | Yes |
 | `seo-mapping` | `mapping` | `create-task` | `--url` `--keyword` | Yes |
 | `topical-authority` | `topical` | `topics` | `--keyword` | No |
@@ -87,7 +87,7 @@ seogpt:               generate, raw
 seogpt2:              create-task, get-task-status, get-result, raw
 seogpt-compare:       create-task, get-task-status, get-result, raw
 seo-mapping:          create-task, get-task-status, get-result, raw
-topical-authority:    topics, content, raw
+topical-authority:    topics, raw
 top-competitors:      analyze, raw
 marketplace-services: search, raw
 content-quality:      analyze, raw
@@ -112,6 +112,7 @@ sv options seogpt type --search meta
 # Shorthand subcommands (where available)
 sv seogpt types
 sv seogpt types --search meta
+sv seogpt lengths
 sv seogpt languages
 sv seogpt engines
 sv image types
@@ -128,6 +129,7 @@ sv seo-mapping types
 sv better-keywords types
 sv better-keywords languages
 sv content-transformer types
+sv content-transformer lengths
 sv content-transformer languages
 sv ranklens languages
 sv ranklens engines
@@ -241,8 +243,8 @@ sv --format json task result TASK_ID --tool geo-audit
 ### Pattern 3: Direct tool polling
 
 ```bash
-sv geo-audit get-task-status --task_id TASK_ID --format json
-sv geo-audit get-result --task_id TASK_ID --format json
+sv geo-audit get-task-status --task-id TASK_ID --format json
+sv geo-audit get-result --task-id TASK_ID --format json
 ```
 
 Same for `seogpt2`, `seogpt-compare`, `seo-mapping` — replace `geo-audit` with the tool name.
@@ -253,14 +255,17 @@ Same for `seogpt2`, `seogpt-compare`, `seo-mapping` — replace `geo-audit` with
 
 These differ from the standard pattern — get them wrong and the call fails.
 
-### seogpt2 — `--keyword` maps to `Topic`, not `kw`
+### seogpt2 — `--topic` maps to `Topic` (required), `--keyword`/`--kw` is a separate field
 
 ```bash
-# CORRECT — --keyword sends value as "Topic" API field
-sv seogpt2 create-task --keyword "White Label SEO for Agencies" --type on-page-blog-article --wait --strict --no-fuzzy --non-interactive --format json
+# CORRECT — --topic sends value as the required "Topic" API field
+sv seogpt2 create-task --topic "White Label SEO for Agencies" --type on-page-blog-article --wait --strict --no-fuzzy --non-interactive --format json
 
-# WRONG — no other flag maps to Topic
-sv seogpt2 create-task --text "..." ...   # also maps to Topic, use --keyword
+# --title is an alias for --topic (same field)
+sv seogpt2 create-task --title "White Label SEO for Agencies" --type on-page-blog-article --wait --strict --no-fuzzy --non-interactive --format json
+
+# --keyword/--kw maps to the separate, optional KW field — it does NOT set Topic
+sv seogpt2 create-task --topic "White Label SEO for Agencies" --keyword "white label seo" --type on-page-blog-article --wait --strict --no-fuzzy --non-interactive --format json
 ```
 
 ### better-keywords `filter` — requires `data` array from prior `research` call
@@ -288,11 +293,12 @@ No CLI flag exists for `mgptid`. Must use raw call:
 
 ```bash
 # Step 1 — get MGPTID from rank response
-sv ranklens rank --keyword "white label seo" --url https://example.com --format json
+sv ranklens rank --entity "white label seo" --url https://example.com --format json
 # → parse response["data"]["MGPTID"]
+# response["data"] always uses "entity", never "keyword" — --keyword/--kw still works as an input alias, but the response field name is always "entity"
 
 # Step 2 — pass MGPTID via raw call
-sv --format json call ranklens --json '{"action":"competitors","mgptid":"MGPTID_VALUE","web":"https://example.com","kw":"white label seo"}'
+sv --format json call ranklens --json '{"action":"competitors","mgptid":"MGPTID_VALUE","web":"https://example.com","entity":"white label seo"}'
 ```
 
 ### `sv task status/result` — `--format` must be global
@@ -313,7 +319,7 @@ sv task status TASK_ID --tool geo-audit --format json
 |---|---|---|
 | `Could not resolve --type "X" in strict mode` | Value is not a valid slug or ID | Run `sv options TOOL type` → use `id` or `slug` column |
 | `Could not resolve --type "X"` (no strict) | No match found at any level | Run `sv options TOOL type --search X` to find closest match |
-| `Topic is required` | seogpt2 called without `--keyword` | Add `--keyword "your topic"` |
+| `Topic is required` | seogpt2 called without `--topic` | Add `--topic "your topic"` |
 | `task_id is invalid` | Task has expired on the server | Create a new task |
 | `No local tool mapping found for task` | Task not in `~/.sv/tasks.json` | Add `--tool TOOL_NAME` explicitly |
 | `API authentication failed: HTTP 401` | Bad or missing API key | Check `SV_API_KEY` environment variable |
@@ -331,7 +337,7 @@ When friendly flags are insufficient, send the payload directly. The CLI injects
 ```bash
 sv --format json call seogpt --json '{"action":"generate","kw":"white label seo","type":18}'
 sv --format json call geo-audit --json '{"action":"createTask","kw":"white label seo","URL":"https://example.com"}'
-sv --format json call ranklens --json '{"action":"competitors","mgptid":"...","web":"https://example.com","kw":"white label seo"}'
+sv --format json call ranklens --json '{"action":"competitors","mgptid":"...","web":"https://example.com","entity":"white label seo"}'
 ```
 
 From a file:
@@ -370,12 +376,12 @@ sv --format json call better-keywords --json '{"action":"filter","kw":"white lab
 sv content-transformer rewrite --text "SEO services for agencies" --keyword "white label seo" --strict --no-fuzzy --non-interactive --format json
 sv core-analysis analyze --url https://example.com --keyword "white label seo" --strict --no-fuzzy --non-interactive --format json
 sv geo-audit create-task --url https://example.com --keyword "white label seo" --wait --strict --no-fuzzy --non-interactive --format json
-sv insight-igniter entities --url https://example.com --keyword "white label seo" --strict --no-fuzzy --non-interactive --format json
+sv insight-igniter entities --url https://example.com --strict --no-fuzzy --non-interactive --format json
 sv preliminary-audit analyze --url https://example.com --strict --no-fuzzy --non-interactive --format json
-sv ranklens rank --keyword "white label seo" --url https://example.com --strict --no-fuzzy --non-interactive --format json
+sv ranklens rank --entity "white label seo" --url https://example.com --strict --no-fuzzy --non-interactive --format json
 sv seo-image generate --keyword "white label seo" --type 33 --strict --no-fuzzy --non-interactive --format json
 sv seogpt generate --keyword "white label seo" --type 18 --strict --no-fuzzy --non-interactive --format json
-sv seogpt2 create-task --keyword "White Label SEO for Agencies" --type 0 --wait --strict --no-fuzzy --non-interactive --format json
+sv seogpt2 create-task --topic "White Label SEO for Agencies" --type 0 --wait --strict --no-fuzzy --non-interactive --format json
 sv seogpt-compare create-task --url https://example.com --keyword "white label seo" --wait --strict --no-fuzzy --non-interactive --format json
 sv seo-mapping create-task --url https://example.com --keyword "white label seo" --wait --strict --no-fuzzy --non-interactive --format json
 sv topical-authority topics --keyword "white label seo" --strict --no-fuzzy --non-interactive --format json

{sv_cli-0.3.0 → sv_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: sv-cli
-Version: 0.3.0
+Version: 0.5.0
 Summary: Open-source, definition-driven command-line client for SV AI API tools.
 Project-URL: Homepage, https://github.com/seovendorco/sv-cli
 Project-URL: Issues, https://github.com/seovendorco/sv-cli/issues
@@ -175,7 +175,7 @@ The canonical API tool keys are discovered from the live API root; local aliases
 
 ## Enum resolution
 
-For enum-heavy fields such as content type, language, engine, image type, theme, background, color, and size, the CLI resolves values in this order:
+For enum-heavy fields such as content type, content length, language, engine, image type, theme, background, color, and size, the CLI resolves values in this order:
 
 1. Numeric ID exact match
 2. Exact slug match
@@ -196,6 +196,12 @@ Examples that all resolve to Meta Description (id 18):
 --type "meta desc"
 ```
 
+`--length`/`--contentlength` (content length by ID, slug, or label — run `sv TOOL lengths` for valid values) resolves the same way:
+
+```bash
+sv seogpt generate --keyword "white label seo" --type 18 --length 300
+```
+
 > **Note:** Fuzzy matching is enabled by default. Use `--strict --no-fuzzy` in scripts to require exact ID or slug and avoid unintended matches.
 
 Agent-safe mode:
@@ -246,10 +252,10 @@ sv task status TASK_ID --tool geo-audit
 sv task result TASK_ID --tool geo-audit
 ```
 
-`seogpt2` is another async tool. Its required field is `Topic` (a title or subject), mapped via `--keyword`:
+`seogpt2` is another async tool. Its required field is `Topic` (a title or subject), mapped via `--topic` (`--title` is an alias for the same field). `--keyword`/`--kw` is a separate, optional field for additional keywords — it does not set the topic:
 
 ```bash
-sv seogpt2 create-task --keyword "White Label SEO for Agencies" --type on-page-blog-article --wait
+sv seogpt2 create-task --topic "White Label SEO for Agencies" --type on-page-blog-article --wait
 ```
 
 See available types with `sv seogpt2 types`, lengths with `sv seogpt2 lengths`, engines with `sv seogpt2 engines`.
@@ -258,8 +264,8 @@ Manual 3-step flow (without `--wait`):
 
 ```bash
 sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo"
-sv geo-audit get-task-status --task_id TASK_ID
-sv geo-audit get-result --task_id TASK_ID
+sv geo-audit get-task-status --task-id TASK_ID
+sv geo-audit get-result --task-id TASK_ID
 ```
 
 > **Note:** `--format` is not available on `sv task status` or `sv task result` directly. Place it before `task` as a global flag:

{sv_cli-0.3.0 → sv_cli-0.5.0}/README.md

@@ -140,7 +140,7 @@ The canonical API tool keys are discovered from the live API root; local aliases
 
 ## Enum resolution
 
-For enum-heavy fields such as content type, language, engine, image type, theme, background, color, and size, the CLI resolves values in this order:
+For enum-heavy fields such as content type, content length, language, engine, image type, theme, background, color, and size, the CLI resolves values in this order:
 
 1. Numeric ID exact match
 2. Exact slug match
@@ -161,6 +161,12 @@ Examples that all resolve to Meta Description (id 18):
 --type "meta desc"
 ```
 
+`--length`/`--contentlength` (content length by ID, slug, or label — run `sv TOOL lengths` for valid values) resolves the same way:
+
+```bash
+sv seogpt generate --keyword "white label seo" --type 18 --length 300
+```
+
 > **Note:** Fuzzy matching is enabled by default. Use `--strict --no-fuzzy` in scripts to require exact ID or slug and avoid unintended matches.
 
 Agent-safe mode:
@@ -211,10 +217,10 @@ sv task status TASK_ID --tool geo-audit
 sv task result TASK_ID --tool geo-audit
 ```
 
-`seogpt2` is another async tool. Its required field is `Topic` (a title or subject), mapped via `--keyword`:
+`seogpt2` is another async tool. Its required field is `Topic` (a title or subject), mapped via `--topic` (`--title` is an alias for the same field). `--keyword`/`--kw` is a separate, optional field for additional keywords — it does not set the topic:
 
 ```bash
-sv seogpt2 create-task --keyword "White Label SEO for Agencies" --type on-page-blog-article --wait
+sv seogpt2 create-task --topic "White Label SEO for Agencies" --type on-page-blog-article --wait
 ```
 
 See available types with `sv seogpt2 types`, lengths with `sv seogpt2 lengths`, engines with `sv seogpt2 engines`.
@@ -223,8 +229,8 @@ Manual 3-step flow (without `--wait`):
 
 ```bash
 sv geo-audit create-task --url https://example.com --keyword "seo agency,white label seo"
-sv geo-audit get-task-status --task_id TASK_ID
-sv geo-audit get-result --task_id TASK_ID
+sv geo-audit get-task-status --task-id TASK_ID
+sv geo-audit get-result --task-id TASK_ID
 ```
 
 > **Note:** `--format` is not available on `sv task status` or `sv task result` directly. Place it before `task` as a global flag:

{sv_cli-0.3.0 → sv_cli-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sv-cli"
-version = "0.3.0"
+version = "0.5.0"
 description = "Open-source, definition-driven command-line client for SV AI API tools."
 readme = "README.md"
 requires-python = ">=3.10"

{sv_cli-0.3.0 → sv_cli-0.5.0}/src/sv_cli/__init__.py

@@ -1,3 +1,3 @@
 """SV CLI package."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{sv_cli-0.3.0 → sv_cli-0.5.0}/src/sv_cli/adapters.py

@@ -31,11 +31,19 @@ class ToolAdapter:
 COMMON_FIELD_ALIASES: dict[str, tuple[str, ...]] = {
     "keyword": ("keyword", "kw", "query", "seed_keyword"),
     "keywords": ("keywords", "kws", "keyword_list", "kwlist"),
+    "topic": ("topic", "title"),
+    # Deliberately narrow: no "kw"/"keyword" fallback here, unlike "keyword" above.
+    # Those are common to many unrelated tools (better-keywords, seogpt2, ...) and
+    # would make --entity spuriously "relevant" (and functional, just semantically
+    # wrong) for all of them. RankLens overrides this below with its own aliases.
+    "entity": ("entity", "entities"),
+    "task_id": ("task_id", "taskid", "task-id"),
     "url": ("url", "domain", "page_url", "website"),
     "url_a": ("url_a", "urla", "url1", "first_url", "competitor_url"),
     "url_b": ("url_b", "urlb", "url2", "second_url", "comparison_url"),
     "brand": ("brand", "brand_name", "company", "company_name"),
     "type": ("contenttype", "content_type", "imagetype", "image_type", "type"),
+    "length": ("contentlength", "content_length", "length"),
     "language": ("language", "lang", "language_id"),
     "engine": ("engine", "ai_engine", "model"),
     "country": ("country", "country_code", "location", "gl"),
@@ -127,7 +135,14 @@ TOOL_ADAPTERS: dict[str, ToolAdapter] = {
         aliases=(),
         default_action="rank",
         actions=("rank", "competitors", "raw"),
-        field_aliases=COMMON_FIELD_ALIASES,
+        field_aliases={
+            **COMMON_FIELD_ALIASES,
+            # "entity" is RankLens's real, documented field. --keyword/--kw remain
+            # accepted as aliases (the API still honors kw/keyword input too), but
+            # should resolve onto entity now rather than the deprecated field names.
+            "keyword": ("entity", "kw", "keyword", "query", "seed_keyword"),
+            "entity": ("entity", "entities", "kw", "keyword", "query", "seed_keyword"),
+        },
         option_aliases={
             "languages": ("lang", "language", "languages"),
             "engines": ("engine", "model", "engines"),
@@ -176,8 +191,13 @@ TOOL_ADAPTERS: dict[str, ToolAdapter] = {
         actions=("create-task", "get-task-status", "get-result", "raw"),
         field_aliases={
             **COMMON_FIELD_ALIASES,
-            "keyword": ("Topic", "topic", "kw", "keyword", "query", "seed_keyword"),
-            "text": ("Topic", "topic", "text", "content", "input", "body"),
+            # The real backend (SEOB's seogpt2api.php) treats these as two distinct
+            # fields: Topic (required, 12-200 chars, the article subject) and KW
+            # (optional, up to 5 keywords). --keyword/--kw/--keywords must all land
+            # on KW, never on Topic - --topic/--title are the only way to set Topic.
+            "keyword": ("KW", "kw", "keywords", "keyword", "query", "seed_keyword"),
+            "keywords": ("KW", "kw", "keywords", "keyword", "keyword_list", "kwlist"),
+            "topic": ("Topic", "topic", "title"),
         },
         async_likely=True,
         option_aliases={
@@ -222,7 +242,7 @@ TOOL_ADAPTERS: dict[str, ToolAdapter] = {
         command="topical-authority",
         aliases=("topical",),
         default_action="topics",
-        actions=("topics", "content", "raw"),
+        actions=("topics", "raw"),
         field_aliases=COMMON_FIELD_ALIASES,
         option_aliases={
             "modes": ("topicmode", "topic_mode", "mode", "modes"),

{sv_cli-0.3.0 → sv_cli-0.5.0}/src/sv_cli/api_client.py

@@ -24,9 +24,13 @@ class APIResponse:
 
 
 class APIClient:
-    def __init__(self, *, debug: bool = False, console: Console | None = None) -> None:
+    def __init__(self, *, debug: bool = False, console: Console | None = None, client_type: str | None = None) -> None:
         self.debug = debug
         self.console = console or Console(stderr=True)
+        # Identifies this process to the SV API as "cli" or "mcp" (X-SV-Client header)
+        # for usage tracking. None means the caller didn't specify one - the header is
+        # simply omitted, and the API buckets the call as generic "api" usage.
+        self.client_type = client_type
 
     def request_tool(
         self,
@@ -35,13 +39,14 @@ class APIClient:
         payload: dict[str, Any],
         api_key: str | None,
         method: str = "POST",
-        timeout: float = 60.0,
+        timeout: float = 300.0,
     ) -> APIResponse:
         final_payload = dict(payload)
         if api_key and not any(key in final_payload for key in ("k", "api_key", "apikey", "key")):
             final_payload["k"] = api_key
 
         method = method.upper()
+        headers = {"X-SV-Client": self.client_type} if self.client_type else None
         if self.debug:
             parsed = urlparse(endpoint)
             shown_path = parsed.path or endpoint
@@ -50,7 +55,7 @@ class APIClient:
 
         started = time.perf_counter()
         try:
-            with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+            with httpx.Client(timeout=timeout, follow_redirects=True, headers=headers) as client:
                 if method == "GET":
                     response = client.get(endpoint, params=final_payload)
                 elif method in {"POST", "PUT", "PATCH"}:

{sv_cli-0.3.0 → sv_cli-0.5.0}/src/sv_cli/executor.py

@@ -120,6 +120,7 @@ def execute_tool(
     raw_payload: dict[str, Any] | None = None,
     method: str = "POST",
     console: Console | None = None,
+    client_type: str | None = None,
 ) -> Any:
     console = console or Console()
     definitions = DefinitionsManager(runtime.base_url)
@@ -149,7 +150,7 @@ def execute_tool(
             non_interactive=runtime.non_interactive,
         )
 
-    client = APIClient(debug=runtime.debug, console=Console(stderr=True))
+    client = APIClient(debug=runtime.debug, console=Console(stderr=True), client_type=client_type)
     response = client.request_tool(endpoint=str(endpoint), payload=payload, api_key=api_key, method=method)
     data = response.data