geonode-scraper-cli 0.1.0__tar.gz

geonode_scraper_cli-0.1.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: geonode-scraper-cli
+Version: 0.1.0
+Summary: Command-line interface for the Geonode Scraper API
+Author: Geonode Team
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: geonode-scraper-tools-core>=0.3.1
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.12.11; extra == "dev"
+
+# Geonode Scraper CLI
+
+`gscraper` is the command-line interface for the Geonode Scraper API. It is a thin
+presentation layer over [`geonode-scraper-tools-core`](../python-agent-tools-core):
+commands parse flags, resolve configuration, call a stable service method, and
+render the result. All domain logic (validation, polling, retries) lives in the
+service layer, not in the CLI.
+
+## Requirements
+
+- Python 3.10+
+- Works on **Linux**, **macOS**, and **Windows**
+
+## Installation
+
+**Recommended — install as a standalone tool with [pipx](https://pipx.pypa.io):**
+
+```sh
+pipx install geonode-scraper-cli
+```
+
+`pipx` installs `gscraper` into its own isolated virtual environment and puts it
+on your `PATH`, so it never conflicts with other Python projects. This is the
+preferred way to install CLI tools globally.
+
+**Alternative — install with pip:**
+
+```sh
+pip install geonode-scraper-cli
+```
+
+> **Windows note:** on Windows the `gscraper` command is placed in the Python
+> Scripts folder (e.g. `%APPDATA%\Python\Python3xx\Scripts`). If the command is
+> not found after installation, add that folder to your `PATH`, or use
+> `python -m geonode_scraper_cli` as a fallback. `pipx` handles this
+> automatically and is the simpler choice on Windows.
+
+## Configuration
+
+Configuration is resolved with the following precedence (highest first):
+
+1. Command-line flags (`--api-key`, `--host`, ...)
+2. Environment variables (`GEONODE_SCRAPER_API_KEY`, `GEONODE_SCRAPER_HOST`,
+   `GEONODE_SCRAPER_VERIFY_SSL`, `GEONODE_SCRAPER_TIMEOUT`, `GEONODE_SCRAPER_PROFILE`)
+3. A TOML config file at `~/.config/geonode-scraper/config.toml`
+4. Built-in defaults
+
+Prefer environment variables or the config file for your API key — passing
+`--api-key` on the command line can leak it into your shell history.
+
+Example `~/.config/geonode-scraper/config.toml`:
+
+```toml
+[default]
+host = "https://api.example.com"
+api_key = "your-api-key"
+verify_ssl = true
+
+[staging]
+host = "https://staging.example.com"
+api_key = "your-staging-key"
+```
+
+Select a non-default profile with `--profile staging` or
+`GEONODE_SCRAPER_PROFILE=staging`. Inspect the active configuration with:
+
+```sh
+gscraper config path     # print the config file location
+gscraper config show     # show profiles (API keys masked)
+```
+
+## Output
+
+Commands print a human-readable summary by default. Use `--json` or `--yaml`
+to print the raw result envelope for scripting. These flags can appear either
+before the subcommand (global position) or after it (per-command position) —
+both work:
+
+```sh
+gscraper extract https://example.com --json | jq -r .result.data.markdown
+gscraper --json extract https://example.com | jq -r .result.data.markdown
+```
+
+The JSON/YAML envelope has the shape `{ "ok": bool, "operation": str, "result": {...} }`
+on success, or `{ "ok": false, "operation": str, "error": {...} }` on failure.
+
+## Commands
+
+```text
+gscraper extract URL [--format markdown|html] [--render-js] [--async] \
+                     [--proxy-country US] [--proxy-type residential] \
+                     [--header "K: V"] [--output out.md]
+
+gscraper jobs get JOB_ID
+gscraper jobs list [--status completed] [--url ...] [--page N]
+gscraper jobs wait JOB_ID [--timeout S] [--interval S]
+
+gscraper batch create URL [URL ...] [--format markdown]
+gscraper batch status JOB_ID
+gscraper batch wait JOB_ID [--timeout S] [--interval S]
+gscraper batch list [--status ...]
+gscraper batch cancel JOB_ID
+
+gscraper crawl create URL [--depth 2] [--limit 50] [--include-subdomains]
+gscraper crawl status JOB_ID
+gscraper crawl wait JOB_ID
+gscraper crawl list [--url ...]
+gscraper crawl cancel JOB_ID
+
+gscraper map run URL [--search term] [--no-subdomains]   # primary action
+gscraper map jobs list                                   # inspect past map jobs
+gscraper map jobs get JOB_ID
+
+gscraper stats [--start-date ISO] [--end-date ISO]
+gscraper health
+```
+
+Run `gscraper --help` or `gscraper <command> --help` for full details.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Usage / invalid arguments |
+| 4 | Authentication / authorization (401, 403) |
+| 5 | Not found (404) |
+| 6 | Validation error (422) |
+| 7 | Network / connection error |
+| 8 | Polling timeout (`wait` commands) |
+
+## Shell completion
+
+```sh
+gscraper --install-completion
+```

geonode_scraper_cli-0.1.0/README.md

@@ -0,0 +1,137 @@
+# Geonode Scraper CLI
+
+`gscraper` is the command-line interface for the Geonode Scraper API. It is a thin
+presentation layer over [`geonode-scraper-tools-core`](../python-agent-tools-core):
+commands parse flags, resolve configuration, call a stable service method, and
+render the result. All domain logic (validation, polling, retries) lives in the
+service layer, not in the CLI.
+
+## Requirements
+
+- Python 3.10+
+- Works on **Linux**, **macOS**, and **Windows**
+
+## Installation
+
+**Recommended — install as a standalone tool with [pipx](https://pipx.pypa.io):**
+
+```sh
+pipx install geonode-scraper-cli
+```
+
+`pipx` installs `gscraper` into its own isolated virtual environment and puts it
+on your `PATH`, so it never conflicts with other Python projects. This is the
+preferred way to install CLI tools globally.
+
+**Alternative — install with pip:**
+
+```sh
+pip install geonode-scraper-cli
+```
+
+> **Windows note:** on Windows the `gscraper` command is placed in the Python
+> Scripts folder (e.g. `%APPDATA%\Python\Python3xx\Scripts`). If the command is
+> not found after installation, add that folder to your `PATH`, or use
+> `python -m geonode_scraper_cli` as a fallback. `pipx` handles this
+> automatically and is the simpler choice on Windows.
+
+## Configuration
+
+Configuration is resolved with the following precedence (highest first):
+
+1. Command-line flags (`--api-key`, `--host`, ...)
+2. Environment variables (`GEONODE_SCRAPER_API_KEY`, `GEONODE_SCRAPER_HOST`,
+   `GEONODE_SCRAPER_VERIFY_SSL`, `GEONODE_SCRAPER_TIMEOUT`, `GEONODE_SCRAPER_PROFILE`)
+3. A TOML config file at `~/.config/geonode-scraper/config.toml`
+4. Built-in defaults
+
+Prefer environment variables or the config file for your API key — passing
+`--api-key` on the command line can leak it into your shell history.
+
+Example `~/.config/geonode-scraper/config.toml`:
+
+```toml
+[default]
+host = "https://api.example.com"
+api_key = "your-api-key"
+verify_ssl = true
+
+[staging]
+host = "https://staging.example.com"
+api_key = "your-staging-key"
+```
+
+Select a non-default profile with `--profile staging` or
+`GEONODE_SCRAPER_PROFILE=staging`. Inspect the active configuration with:
+
+```sh
+gscraper config path     # print the config file location
+gscraper config show     # show profiles (API keys masked)
+```
+
+## Output
+
+Commands print a human-readable summary by default. Use `--json` or `--yaml`
+to print the raw result envelope for scripting. These flags can appear either
+before the subcommand (global position) or after it (per-command position) —
+both work:
+
+```sh
+gscraper extract https://example.com --json | jq -r .result.data.markdown
+gscraper --json extract https://example.com | jq -r .result.data.markdown
+```
+
+The JSON/YAML envelope has the shape `{ "ok": bool, "operation": str, "result": {...} }`
+on success, or `{ "ok": false, "operation": str, "error": {...} }` on failure.
+
+## Commands
+
+```text
+gscraper extract URL [--format markdown|html] [--render-js] [--async] \
+                     [--proxy-country US] [--proxy-type residential] \
+                     [--header "K: V"] [--output out.md]
+
+gscraper jobs get JOB_ID
+gscraper jobs list [--status completed] [--url ...] [--page N]
+gscraper jobs wait JOB_ID [--timeout S] [--interval S]
+
+gscraper batch create URL [URL ...] [--format markdown]
+gscraper batch status JOB_ID
+gscraper batch wait JOB_ID [--timeout S] [--interval S]
+gscraper batch list [--status ...]
+gscraper batch cancel JOB_ID
+
+gscraper crawl create URL [--depth 2] [--limit 50] [--include-subdomains]
+gscraper crawl status JOB_ID
+gscraper crawl wait JOB_ID
+gscraper crawl list [--url ...]
+gscraper crawl cancel JOB_ID
+
+gscraper map run URL [--search term] [--no-subdomains]   # primary action
+gscraper map jobs list                                   # inspect past map jobs
+gscraper map jobs get JOB_ID
+
+gscraper stats [--start-date ISO] [--end-date ISO]
+gscraper health
+```
+
+Run `gscraper --help` or `gscraper <command> --help` for full details.
+
+## Exit codes
+
+| Code | Meaning |
+| ---- | ------- |
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Usage / invalid arguments |
+| 4 | Authentication / authorization (401, 403) |
+| 5 | Not found (404) |
+| 6 | Validation error (422) |
+| 7 | Network / connection error |
+| 8 | Polling timeout (`wait` commands) |
+
+## Shell completion
+
+```sh
+gscraper --install-completion
+```

geonode_scraper_cli-0.1.0/geonode_scraper_cli/__init__.py

@@ -0,0 +1,3 @@
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

geonode_scraper_cli-0.1.0/geonode_scraper_cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Typer command modules for the gscraper CLI."""

geonode_scraper_cli-0.1.0/geonode_scraper_cli/commands/_common.py

@@ -0,0 +1,42 @@
+"""Helpers shared across command modules."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import typer
+
+from ..errors import ExitCode
+from ..output import OutputFormat
+
+
+def apply_output_override(ctx: typer.Context, as_json: bool, as_yaml: bool) -> None:
+    """Override the output format set by the global --json/--yaml flags.
+
+    Allows per-command placement: ``gscraper extract https://example.com --json``.
+    """
+    if as_json and as_yaml:
+        raise typer.BadParameter("Use only one of --json or --yaml.")
+    if as_json:
+        ctx.obj.output = OutputFormat.JSON
+    elif as_yaml:
+        ctx.obj.output = OutputFormat.YAML
+
+
+def parse_headers(raw_headers: Iterable[str] | None) -> dict[str, str] | None:
+    """Parse repeated ``--header "Key: Value"`` flags into a dict."""
+    if not raw_headers:
+        return None
+    headers: dict[str, str] = {}
+    for item in raw_headers:
+        if ":" not in item:
+            typer.echo(f"Invalid header '{item}'. Expected 'Key: Value'.", err=True)
+            raise typer.Exit(int(ExitCode.USAGE))
+        key, value = item.split(":", 1)
+        headers[key.strip()] = value.strip()
+    return headers
+
+
+def optional(**kwargs: object) -> dict[str, object]:
+    """Drop keys whose value is ``None`` so schema defaults apply."""
+    return {key: value for key, value in kwargs.items() if value is not None}

geonode_scraper_cli-0.1.0/geonode_scraper_cli/commands/batch.py

@@ -0,0 +1,114 @@
+"""`gscraper batch` — submit and manage batch extraction jobs."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+from geonode_scraper_tools_core.schemas import (
+    CreateBatchInput,
+    GetBatchStatusInput,
+    ListBatchJobsInput,
+    WaitForBatchInput,
+)
+
+from ..invoke import call, validated
+from ._common import apply_output_override, optional, parse_headers
+
+batch_app = typer.Typer(help="Submit and manage batch extraction jobs.", no_args_is_help=True)
+
+
+@batch_app.command("create")
+def create(
+    ctx: typer.Context,
+    urls: List[str] = typer.Argument(..., help="One or more URLs to extract."),
+    formats: Optional[List[str]] = typer.Option(None, "--format", "-f", help="Output format(s). Repeatable."),
+    render_js: bool = typer.Option(False, "--render-js", help="Render JavaScript with a headless browser."),
+    proxy_country: Optional[str] = typer.Option(None, "--proxy-country", help="ISO 3166-1 alpha-2 country code."),
+    proxy_type: Optional[str] = typer.Option(None, "--proxy-type", help="Proxy type: datacenter, residential, mix."),
+    header: Optional[List[str]] = typer.Option(None, "--header", "-H", help="Request header 'Key: Value'. Repeatable."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Submit multiple URLs in a single batch job."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        CreateBatchInput,
+        urls=urls,
+        render_js=render_js,
+        **optional(
+            formats=formats,
+            proxy_country=proxy_country,
+            proxy_type=proxy_type,
+            headers=parse_headers(header),
+        ),
+    )
+    call(ctx, "create_batch", payload)
+
+
+@batch_app.command("status")
+def status(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Batch job ID."),
+    page: int = typer.Option(1, "--page", help="Page number."),
+    page_size: int = typer.Option(10, "--page-size", help="Results per page (max 50)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Show the status and per-URL results of a batch job."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(GetBatchStatusInput, job_id=job_id, page=page, page_size=page_size)
+    call(ctx, "get_batch_status", payload)
+
+
+@batch_app.command("wait")
+def wait(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Batch job ID."),
+    timeout_seconds: Optional[float] = typer.Option(None, "--timeout", help="Polling timeout override (seconds)."),
+    poll_interval_seconds: Optional[float] = typer.Option(None, "--interval", help="Polling interval override (s)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Poll a batch job until it reaches a terminal state."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        WaitForBatchInput,
+        job_id=job_id,
+        **optional(timeout_seconds=timeout_seconds, poll_interval_seconds=poll_interval_seconds),
+    )
+    call(ctx, "wait_for_batch", payload)
+
+
+@batch_app.command("list")
+def list_jobs(
+    ctx: typer.Context,
+    status: Optional[str] = typer.Option(None, "--status", help="queued|processing|completed|failed|cancelled."),
+    start_date: Optional[str] = typer.Option(None, "--start-date", help="ISO 8601 lower bound."),
+    end_date: Optional[str] = typer.Option(None, "--end-date", help="ISO 8601 upper bound."),
+    page: int = typer.Option(1, "--page", help="Page number."),
+    page_size: int = typer.Option(100, "--page-size", help="Results per page (max 100)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """List and filter batch jobs."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        ListBatchJobsInput,
+        page=page,
+        page_size=page_size,
+        **optional(status=status, start_date=start_date, end_date=end_date),
+    )
+    call(ctx, "list_batch_jobs", payload)
+
+
+@batch_app.command("cancel")
+def cancel(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Batch job ID to cancel."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Cancel a running batch job."""
+    apply_output_override(ctx, as_json, as_yaml)
+    call(ctx, "cancel_batch", {"job_id": job_id})

geonode_scraper_cli-0.1.0/geonode_scraper_cli/commands/config.py

@@ -0,0 +1,48 @@
+"""`gscraper config` — inspect CLI configuration (read-only)."""
+
+from __future__ import annotations
+
+import typer
+
+from ..config import ConfigError, config_path, load_profiles, resolve_profile_name
+from ..context import get_cli_context
+from ..errors import ExitCode
+from ..renderers import console
+
+config_app = typer.Typer(help="Inspect CLI configuration.", no_args_is_help=True)
+
+
+@config_app.command("path")
+def path() -> None:
+    """Print the location of the TOML config file."""
+    typer.echo(str(config_path()))
+
+
+@config_app.command("show")
+def show(ctx: typer.Context) -> None:
+    """Show the active profile and config file contents (API keys masked)."""
+    cli = get_cli_context(ctx)
+    profile = resolve_profile_name(cli.profile)
+    try:
+        profiles = load_profiles()
+    except ConfigError as exc:
+        typer.echo(str(exc), err=True)
+        raise typer.Exit(int(ExitCode.USAGE)) from exc
+
+    out = console()
+    out.print(f"config file: {config_path()}")
+    out.print(f"active profile: {profile}")
+    if not profiles:
+        out.print("[yellow]No config file found.[/yellow]")
+        return
+    masked = {name: _mask(section) for name, section in profiles.items()}
+    out.print_json(data=masked)
+
+
+def _mask(section: object) -> object:
+    if not isinstance(section, dict):
+        return section
+    redacted = dict(section)
+    if "api_key" in redacted and redacted["api_key"]:
+        redacted["api_key"] = "***"
+    return redacted

geonode_scraper_cli-0.1.0/geonode_scraper_cli/commands/crawl.py

@@ -0,0 +1,119 @@
+"""`gscraper crawl` — submit and manage site crawl jobs."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+import typer
+from geonode_scraper_tools_core.schemas import (
+    CreateCrawlInput,
+    GetCrawlStatusInput,
+    ListCrawlJobsInput,
+    WaitForCrawlInput,
+)
+
+from ..invoke import call, validated
+from ._common import apply_output_override, optional
+
+crawl_app = typer.Typer(help="Submit and manage site crawl jobs.", no_args_is_help=True)
+
+
+@crawl_app.command("create")
+def create(
+    ctx: typer.Context,
+    url: str = typer.Argument(..., help="Seed URL to start crawling from."),
+    depth: int = typer.Option(2, "--depth", help="Maximum crawl depth."),
+    limit: int = typer.Option(50, "--limit", help="Maximum number of pages."),
+    formats: Optional[List[str]] = typer.Option(None, "--format", "-f", help="Output format(s). Repeatable."),
+    render_js: bool = typer.Option(False, "--render-js", help="Render JavaScript with a headless browser."),
+    same_domain_only: bool = typer.Option(
+        True, "--same-domain-only/--all-domains", help="Restrict to the seed domain."
+    ),
+    include_subdomains: bool = typer.Option(False, "--include-subdomains", help="Include subdomains when crawling."),
+    proxy_country: Optional[str] = typer.Option(None, "--proxy-country", help="ISO 3166-1 alpha-2 country code."),
+    proxy_type: Optional[str] = typer.Option(None, "--proxy-type", help="Proxy type: datacenter, residential, mix."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Crawl a website from a seed URL up to a depth and page limit."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        CreateCrawlInput,
+        url=url,
+        depth=depth,
+        limit=limit,
+        render_js=render_js,
+        same_domain_only=same_domain_only,
+        include_subdomains=include_subdomains,
+        **optional(formats=formats, proxy_country=proxy_country, proxy_type=proxy_type),
+    )
+    call(ctx, "create_crawl", payload)
+
+
+@crawl_app.command("status")
+def status(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Crawl job ID."),
+    page: int = typer.Option(1, "--page", help="Page number."),
+    page_size: int = typer.Option(10, "--page-size", help="Results per page (max 50)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Show the status and per-page results of a crawl job."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(GetCrawlStatusInput, job_id=job_id, page=page, page_size=page_size)
+    call(ctx, "get_crawl_status", payload)
+
+
+@crawl_app.command("wait")
+def wait(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Crawl job ID."),
+    timeout_seconds: Optional[float] = typer.Option(None, "--timeout", help="Polling timeout override (seconds)."),
+    poll_interval_seconds: Optional[float] = typer.Option(None, "--interval", help="Polling interval override (s)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Poll a crawl job until it reaches a terminal state."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        WaitForCrawlInput,
+        job_id=job_id,
+        **optional(timeout_seconds=timeout_seconds, poll_interval_seconds=poll_interval_seconds),
+    )
+    call(ctx, "wait_for_crawl", payload)
+
+
+@crawl_app.command("list")
+def list_jobs(
+    ctx: typer.Context,
+    url: Optional[str] = typer.Option(None, "--url", help="Filter by seed URL."),
+    status: Optional[str] = typer.Option(None, "--status", help="queued|processing|completed|failed|cancelled."),
+    start_date: Optional[str] = typer.Option(None, "--start-date", help="ISO 8601 lower bound."),
+    end_date: Optional[str] = typer.Option(None, "--end-date", help="ISO 8601 upper bound."),
+    page: int = typer.Option(1, "--page", help="Page number."),
+    page_size: int = typer.Option(100, "--page-size", help="Results per page (max 100)."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """List and filter crawl jobs."""
+    apply_output_override(ctx, as_json, as_yaml)
+    payload = validated(
+        ListCrawlJobsInput,
+        page=page,
+        page_size=page_size,
+        **optional(url=url, status=status, start_date=start_date, end_date=end_date),
+    )
+    call(ctx, "list_crawl_jobs", payload)
+
+
+@crawl_app.command("cancel")
+def cancel(
+    ctx: typer.Context,
+    job_id: str = typer.Argument(..., help="Crawl job ID to cancel."),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON envelope."),
+    as_yaml: bool = typer.Option(False, "--yaml", help="Output raw YAML envelope."),
+) -> None:
+    """Cancel a running crawl job."""
+    apply_output_override(ctx, as_json, as_yaml)
+    call(ctx, "cancel_crawl", {"job_id": job_id})