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

{sv_cli-0.3.0 → sv_cli-0.4.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 |
@@ -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.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sv-cli
-Version: 0.3.0
+Version: 0.4.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.4.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.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sv-cli"
-version = "0.3.0"
+version = "0.4.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.4.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={

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

@@ -35,7 +35,7 @@ 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")):

{sv_cli-0.3.0 → sv_cli-0.4.0}/src/sv_cli/main.py

@@ -31,7 +31,7 @@ from .definitions import DefinitionsManager
 from .errors import CLIError, ConfigError, InvalidInputError
 from .executor import RuntimeOptions, WaitOptions, execute_tool, load_json_payload
 from .formatter import print_output
-from .resolver import extract_option_sets, resolve_api_field, search_candidates
+from .resolver import extract_option_sets, is_cli_field_relevant, resolve_api_field, search_candidates
 from .tasks import get_task_tool, result_payload, status_payload
 from .utils import coerce_jsonish, coerce_mapping_values, parse_key_value_args, read_text_source
 
@@ -39,6 +39,78 @@ console = Console()
 err_console = Console(stderr=True)
 COMMON_CONTEXT_SETTINGS = {"allow_extra_args": True, "ignore_unknown_options": True}
 
+# ---------------------------------------------------------------------------
+# Per-tool/per-action option visibility for --help.
+#
+# The generic option palette in make_action_command() below is shared by every
+# tool+action, but most of its ~25 flags are irrelevant to any given one (e.g.
+# --price/--theme/--color have nothing to do with seogpt2). This section hides
+# irrelevant flags from --help using the live, cached API definitions - the
+# same live_definition-driven approach sv_mcp's schemas.py already uses.
+#
+# --help must stay instant and work offline, so this reads the on-disk
+# definitions cache directly (DefinitionsManager.load_cache()) and never
+# triggers a network fetch. Before the cache is populated (fresh install, or
+# offline), every option stays visible - identical to the old fully-generic
+# behavior - until the user runs a command or `sv definitions refresh`.
+# ---------------------------------------------------------------------------
+
+_DEFINITIONS_CACHE: dict[str, Any] | None = None
+
+
+def _cached_definitions_cache() -> dict[str, Any]:
+    global _DEFINITIONS_CACHE
+    if _DEFINITIONS_CACHE is None:
+        try:
+            _DEFINITIONS_CACHE = DefinitionsManager().load_cache()
+        except Exception:  # noqa: BLE001 - --help must never fail over a cache read
+            _DEFINITIONS_CACHE = {}
+    return _DEFINITIONS_CACHE
+
+
+def _tool_definition(tool: str) -> dict[str, Any]:
+    cache = _cached_definitions_cache()
+    entry = cache.get("tools", {}).get(tool) or {}
+    return entry.get("definition") or {}
+
+
+# create-task/get-task-status/get-result is the identical lifecycle used by every
+# async tool (geogptaudit, seogpt2, seogptcompare, seogptmapping) - confirmed from
+# each tool's index.php, not guessed. The status/result actions only ever need a
+# task_id, regardless of what the create-task action itself accepts.
+TASK_LOOKUP_ACTIONS = {"get-task-status", "get-result"}
+
+# Friendly CLI field names in make_action_command()'s signature, in the order they're
+# declared there. Keep in sync with that function's parameters.
+GENERIC_CLI_FIELDS = (
+    "keyword", "keywords", "topic", "entity", "url", "url_a", "url_b", "brand", "type_value",
+    "length", "language", "engine", "country", "location", "text", "search", "query", "price",
+    "series", "category", "outline", "theme", "background", "color", "size",
+)
+
+# Maps a few typer parameter names to the field_aliases key they're actually resolved
+# under (adapters.py), for the ones where they differ (e.g. "type_value" avoids
+# shadowing the builtin `type`, but resolves as "type").
+_CLI_FIELD_ALIAS_FOR = {"type_value": "type"}
+
+
+def _visible_cli_fields(tool: str, action: str) -> set[str] | None:
+    """Friendly CLI field names relevant to this tool+action, or None for "show all".
+
+    None is the safe fallback: no live definition cached yet, so nothing is hidden.
+    """
+
+    if action in TASK_LOOKUP_ACTIONS:
+        return set()  # every generic content field is irrelevant; task_id is separate
+    definition = _tool_definition(tool)
+    if not definition:
+        return None
+    return {
+        field
+        for field in GENERIC_CLI_FIELDS
+        if is_cli_field_relevant(tool, _CLI_FIELD_ALIAS_FOR.get(field, field), definition)
+    }
+
 app = typer.Typer(
     name="sv",
     help="Definition-driven CLI for SV AI API tools.",
@@ -585,11 +657,15 @@ def build_params(
     *,
     keyword: str | None,
     keywords: str | None,
+    topic: str | None,
+    entity: str | None,
+    task_id: str | None,
     url: str | None,
     url_a: str | None,
     url_b: str | None,
     brand: str | None,
     type_value: str | None,
+    length: str | None,
     language: str | None,
     engine: str | None,
     country: str | None,
@@ -626,11 +702,15 @@ def build_params(
     params: dict[str, Any] = {
         "keyword": keyword,
         "keywords": keywords,
+        "topic": topic,
+        "entity": entity,
+        "task_id": task_id,
         "url": url,
         "url_a": url_a,
         "url_b": url_b,
         "brand": brand,
         "type": type_value,
+        "length": length,
         "language": language,
         "engine": engine,
         "country": country,
@@ -672,32 +752,89 @@ def build_params(
 
 
 def make_action_command(tool: str, action: str):
+    visible = _visible_cli_fields(tool, action)
+
+    def hidden(field: str) -> bool:
+        return visible is not None and field not in visible
+
+    show_task_id = action in TASK_LOOKUP_ACTIONS
+
     def command(
         ctx: typer.Context,
-        keyword: str | None = typer.Option(None, "--keyword", "--kw", help="Primary keyword."),
-        keywords: str | None = typer.Option(None, "--keywords", help="Comma-separated keywords or path to a keyword file."),
-        url: str | None = typer.Option(None, "--url", help="Target URL/domain."),
-        url_a: str | None = typer.Option(None, "--url-a", "--url1", help="First URL for comparison or URL 1."),
-        url_b: str | None = typer.Option(None, "--url-b", "--url2", help="Second URL for comparison or URL 2."),
-        brand: str | None = typer.Option(None, "--brand", help="Brand or company name."),
-        type_value: str | None = typer.Option(None, "--type", help="Type/content type/image type by ID, slug, label, or alias."),
-        language: str | None = typer.Option(None, "--language", help="Language by ID, slug, label, or alias."),
-        engine: str | None = typer.Option(None, "--engine", help="Engine/model by ID, slug, label, or alias."),
-        country: str | None = typer.Option(None, "--country", help="Country/market code where supported."),
-        location: str | None = typer.Option(None, "--location", help="Location/market where supported."),
-        text: str | None = typer.Option(None, "--text", help="Text input for transformer-style tools."),
-        file_path: str | None = typer.Option(None, "--file", help="Read text input from file."),
-        stdin_flag: bool = typer.Option(False, "--stdin", help="Read text input from stdin."),
-        search: str | None = typer.Option(None, "--search", "--searchterm", help="Search term for marketplace/service-style tools."),
-        query: str | None = typer.Option(None, "--query", help="Query/search term where supported."),
-        price: str | None = typer.Option(None, "--price", help="Price ceiling or price filter where supported."),
-        series: str | None = typer.Option(None, "--series", help="Service series filter where supported."),
-        category: str | None = typer.Option(None, "--category", help="Service category filter where supported."),
-        outline: str | None = typer.Option(None, "--outline", help="Outline text or path to outline file."),
-        theme: str | None = typer.Option(None, "--theme", help="Image theme by ID, slug, label, or alias."),
-        background: str | None = typer.Option(None, "--background", help="Image background by ID, slug, label, or alias."),
-        color: str | None = typer.Option(None, "--color", help="Image color/palette by ID, slug, label, or alias."),
-        size: str | None = typer.Option(None, "--size", help="Image size by ID, slug, label, or alias."),
+        topic: str | None = typer.Option(None, "--topic", "--title", help="Article topic or title.", hidden=hidden("topic")),
+        entity: str | None = typer.Option(
+            None, "--entity", "--entities", help="Entity to analyze or discover.", hidden=hidden("entity")
+        ),
+        keyword: str | None = typer.Option(
+            None, "--keyword", "--kw", help="Keyword text.", hidden=hidden("keyword")
+        ),
+        keywords: str | None = typer.Option(
+            None, "--keywords", help="Comma-separated keywords or path to a keyword file.", hidden=hidden("keywords")
+        ),
+        task_id: str | None = typer.Option(
+            None, "--task-id", help="Task ID from a prior create-task call.", hidden=not show_task_id
+        ),
+        url: str | None = typer.Option(None, "--url", help="Target URL/domain.", hidden=hidden("url")),
+        url_a: str | None = typer.Option(
+            None, "--url-a", "--url1", help="First URL for comparison or URL 1.", hidden=hidden("url_a")
+        ),
+        url_b: str | None = typer.Option(
+            None, "--url-b", "--url2", help="Second URL for comparison or URL 2.", hidden=hidden("url_b")
+        ),
+        brand: str | None = typer.Option(None, "--brand", help="Brand or company name.", hidden=hidden("brand")),
+        type_value: str | None = typer.Option(
+            None, "--type", help="Type/content type/image type by ID, slug, label, or alias.", hidden=hidden("type_value")
+        ),
+        length: str | None = typer.Option(
+            None, "--length", "--contentlength", help="Content length by ID, slug, label, or alias.", hidden=hidden("length")
+        ),
+        language: str | None = typer.Option(
+            None, "--language", help="Language by ID, slug, label, or alias.", hidden=hidden("language")
+        ),
+        engine: str | None = typer.Option(
+            None, "--engine", help="Engine/model by ID, slug, label, or alias.", hidden=hidden("engine")
+        ),
+        country: str | None = typer.Option(
+            None, "--country", help="Country/market code where supported.", hidden=hidden("country")
+        ),
+        location: str | None = typer.Option(
+            None, "--location", help="Location/market where supported.", hidden=hidden("location")
+        ),
+        text: str | None = typer.Option(
+            None, "--text", help="Text input for transformer-style tools.", hidden=hidden("text")
+        ),
+        file_path: str | None = typer.Option(None, "--file", help="Read text input from file.", hidden=hidden("text")),
+        stdin_flag: bool = typer.Option(False, "--stdin", help="Read text input from stdin.", hidden=hidden("text")),
+        search: str | None = typer.Option(
+            None, "--search", "--searchterm", help="Search term for marketplace/service-style tools.", hidden=hidden("search")
+        ),
+        query: str | None = typer.Option(
+            None, "--query", help="Query/search term where supported.", hidden=hidden("query")
+        ),
+        price: str | None = typer.Option(
+            None, "--price", help="Price ceiling or price filter where supported.", hidden=hidden("price")
+        ),
+        series: str | None = typer.Option(
+            None, "--series", help="Service series filter where supported.", hidden=hidden("series")
+        ),
+        category: str | None = typer.Option(
+            None, "--category", help="Service category filter where supported.", hidden=hidden("category")
+        ),
+        outline: str | None = typer.Option(
+            None, "--outline", help="Outline text or path to outline file.", hidden=hidden("outline")
+        ),
+        theme: str | None = typer.Option(
+            None, "--theme", help="Image theme by ID, slug, label, or alias.", hidden=hidden("theme")
+        ),
+        background: str | None = typer.Option(
+            None, "--background", help="Image background by ID, slug, label, or alias.", hidden=hidden("background")
+        ),
+        color: str | None = typer.Option(
+            None, "--color", help="Image color/palette by ID, slug, label, or alias.", hidden=hidden("color")
+        ),
+        size: str | None = typer.Option(
+            None, "--size", help="Image size by ID, slug, label, or alias.", hidden=hidden("size")
+        ),
         wait: bool = typer.Option(False, "--wait", help="Wait for async task completion."),
         timeout: int = typer.Option(600, "--timeout", help="Task wait timeout in seconds."),
         poll_interval: int = typer.Option(5, "--poll-interval", help="Task poll interval in seconds."),
@@ -717,11 +854,15 @@ def make_action_command(tool: str, action: str):
         params = build_params(
             keyword=keyword,
             keywords=keywords,
+            topic=topic,
+            entity=entity,
+            task_id=task_id,
             url=url,
             url_a=url_a,
             url_b=url_b,
             brand=brand,
             type_value=type_value,
+            length=length,
             language=language,
             engine=engine,
             country=country,
@@ -811,9 +952,11 @@ def make_tool_app(adapter: ToolAdapter) -> typer.Typer:
     for action in adapter.actions:
         if action == "raw":
             continue
-        tool_app.command(action, context_settings=COMMON_CONTEXT_SETTINGS)(make_action_command(adapter.canonical, action))
+        tool_app.command(action, context_settings=COMMON_CONTEXT_SETTINGS, rich_help_panel="Actions")(
+            make_action_command(adapter.canonical, action)
+        )
 
-    @tool_app.command("raw")
+    @tool_app.command("raw", rich_help_panel="Actions")
     def raw(
         ctx: typer.Context,
         json_payload: str | None = typer.Option(None, "--json", help="Raw JSON payload."),
@@ -839,7 +982,11 @@ def make_tool_app(adapter: ToolAdapter) -> typer.Typer:
             fail(exc)
 
     for command_name, fields in adapter.option_aliases.items():
-        tool_app.command(command_name)(make_option_alias_command(adapter.canonical, fields))
+        tool_app.command(
+            command_name,
+            rich_help_panel="Option lookups (list valid values for a parameter, not an action)",
+            help=f"List valid values for --{fields[0]}.",
+        )(make_option_alias_command(adapter.canonical, fields))
 
     return tool_app
 

{sv_cli-0.3.0 → sv_cli-0.4.0}/src/sv_cli/resolver.py

@@ -333,6 +333,40 @@ def normalize_field(field: str) -> str:
     return str(field).strip().replace("-", "_").replace(" ", "_").lower()
 
 
+def real_field_names(definition: Any) -> set[str]:
+    """Normalized API field names that genuinely appear in a tool's live api_input.
+
+    Used to decide which generic CLI options are relevant to a specific tool,
+    so --help doesn't advertise flags the tool's real API doesn't accept.
+    """
+
+    names: set[str] = set()
+    items = definition.get("api_input") if isinstance(definition, dict) else None
+    if not isinstance(items, list):
+        return names
+    for item in items:
+        if isinstance(item, dict):
+            field = item.get("field")
+            if isinstance(field, str):
+                names.add(normalize_field(field))
+    return names
+
+
+def is_cli_field_relevant(tool: str, cli_field: str, definition: Any) -> bool:
+    """True when a generic CLI field resolves to a real field on this tool's live definition.
+
+    When no live definition is cached yet (e.g. before the first `sv definitions
+    refresh`, or offline), returns True for everything - never hide options based
+    on missing data.
+    """
+
+    if not definition:
+        return True
+    api_field, _candidates = resolve_api_field(tool, cli_field, definition)
+    target_fields = real_field_names(definition) | set(extract_option_sets(definition))
+    return api_field in target_fields
+
+
 def resolve_api_field(tool: str, cli_field: str, definition: Any) -> tuple[str, list[Candidate] | None]:
     """Choose the best API field name for a friendly CLI field."""
 

sv_cli-0.4.0/tests/fixtures/ranklens_definitions.json

@@ -0,0 +1,16 @@
+{
+  "api_input": [
+    {"field": "action", "type": "string", "required": "no", "description": ["rank: Generate RankLens report.", "competitors: Find RankLens competitors."]},
+    {"field": "web", "type": "string", "required": "yes", "description": "Website URL, max 300 characters."},
+    {"field": "entity", "type": "string", "required": "yes", "description": "Entity/keyword text, 4 to 80 characters."},
+    {"field": "kw", "type": "string", "required": "no", "description": "Deprecated alias of entity. Used only when entity is not sent."},
+    {"field": "keyword", "type": "string", "required": "no", "description": "Deprecated alias of entity. Used only when entity and kw are not sent."},
+    {"field": "brand", "type": "string", "required": "no", "description": "Brand text, 0 to 60 characters."},
+    {"field": "location", "type": "string", "required": "no", "description": "Location text, 0 to 100 characters."},
+    {"field": "lang", "type": "integer", "required": "no", "description": null},
+    {"field": "engine", "type": "integer", "required": "no", "description": null},
+    {"field": "mgptid", "type": "string", "required": "no", "description": "Encrypted MGPTID. Required for competitors action, not used for rank action."},
+    {"field": "k", "type": "string", "required": "yes", "description": "API key."}
+  ],
+  "api_output": []
+}