xsoar-cli 2.3.0__tar.gz → 2.4.1__tar.gz

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/CHANGELOG.md

@@ -6,6 +6,35 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-06-17
+
+### Added
+
+- `content get-detached --type all` queries both scripts and playbooks and displays results for each type.
+- `content list --output-format` option (choices: `table`, `json`, `plain`, default: `table`). `table` is human-readable aligned columns, `json` is machine-readable, and `plain` is tab-separated values suitable for piping to tools like `grep`.
+- `content list --search TERM` option. Filters the listed items with a case-insensitive substring match against each item's id, name, and description. Content types and integration brands with no matching items are omitted, and a `No content matching '<term>' found.` message is shown when nothing matches.
+- `content describe --type [script|playbook|command] NAME` command. Shows a single content item in detail: description, arguments, and inputs/outputs. Commands also show the integration brand and its configured instances (name and state). Supports `--output-format [table|json]` (default: `table`). See the [content README](src/xsoar_cli/commands/content/README.md) for details.
+- `case get-context CASENUMBER` command. Retrieves the investigation context tree for a case as JSON, matching `demisto.context()` at runtime. The incident record is not merged in. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
+- `case get-entry ENTRY_ID` command. Retrieves a single War Room entry by its full ID (e.g. `112@153483`) as JSON. The case ID is derived from the entry ID. Exits non-zero with a clear message when the entry ID is malformed or the entry is not found. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
+- `case get-entries CASENUMBER` command. Retrieves all War Room entries for a case as a JSON array, or an empty array when the case has no entries. See the [case README](src/xsoar_cli/commands/case/README.md) for details.
+
+### Changed
+
+- `content get-detached` now prints a human-readable summary instead of raw JSON. Output is a count followed by one line per item in the form `<name> (ID: <id>)`, or `No detached <type> found` when there are none.
+- **Breaking:** `content list` now defaults to a human-readable table instead of JSON. Use `--output-format json` for machine-readable output.
+- `content list` playbook output now shows the playbook ID and description (read from the `comment` field) instead of the name and ID.
+- `content list` command output now shows the command name and description and no longer includes the integration brand. The summary-level JSON structure for commands is now a list of `{name, description}` objects instead of plain command-name strings.
+
+### Removed
+
+- **Breaking:** `content list --detail-level` option, along with its `short`, `extended`, and `full` levels. `content list` now always produces a curated summary. Per-item detail (arguments, inputs, outputs) is available through the `content describe` command.
+
+### Fixed
+
+- `content get-detached` now returns only the content items that are actually detached. The previous query returned all system items, so the command reported every system script (or playbook) as detached instead of just the detached ones. Results are now filtered on each item's `detached` field.
+
+## [2.3.0] - 2026-06-04
+
 ### Added
 
 - `execute command NAME [ARGS]...` runs an automation script or integration command against XSOAR, in the user's playground by default or a specific case with `--case-id`. See the [execute README](src/xsoar_cli/commands/execute/README.md) for details.

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.3.0
+Version: 2.4.1
 Summary: A command-line interface for managing Palo Alto Networks XSOAR (Cortex XSOAR)
 Project-URL: Documentation, https://github.com/tlium/xsoar-cli#readme
 Project-URL: Issues, https://github.com/tlium/xsoar-cli/issues

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '2.3.0'
-__version_tuple__ = version_tuple = (2, 3, 0)
+__version__ = version = '2.4.1'
+__version_tuple__ = version_tuple = (2, 4, 1)
 
 __commit_id__ = commit_id = None

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/pyproject.toml

@@ -68,6 +68,10 @@ exclude_lines = ["no cov", "if __name__ == .__main__.:", "if TYPE_CHECKING:"]
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 
+[tool.ruff]
+line-length = 140
+extend-exclude = ["tests/mock_content"]
+
 [dependency-groups]
 dev = [
     "pytest>=9.0.2",

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/case/README.md

@@ -17,6 +17,53 @@ xsoar-cli case get 312412
 xsoar-cli case get --environment prod 312412
 ```
 
+## Get Context
+
+Retrieve the investigation context tree for a single case. Output is the raw context tree as JSON, matching `demisto.context()` at runtime. The incident record is not merged in.
+
+**Syntax:** `xsoar-cli case get-context [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-context 153483
+xsoar-cli case get-context --environment prod 153483
+```
+
+## Get Entry
+
+Retrieve a single War Room entry by its full ID. Output is the raw entry as JSON. The command exits non-zero with a clear message when no entry with that ID exists in the case.
+
+`ENTRY_ID` is the full entry ID as shown in the GUI, in the form `<n>@<case-id>` (e.g. `112@153483`). The case ID is taken from the entry ID, so it does not need to be supplied separately.
+
+**Syntax:** `xsoar-cli case get-entry [OPTIONS] ENTRY_ID`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-entry 112@153483
+xsoar-cli case get-entry --environment prod 112@153483
+```
+
+## Get Entries
+
+Retrieve all War Room entries for a single case. Output is the full list of entries as a JSON array, or an empty array when the case has no entries.
+
+**Syntax:** `xsoar-cli case get-entries [OPTIONS] CASENUMBER`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+
+**Examples:**
+```
+xsoar-cli case get-entries 153483
+xsoar-cli case get-entries --environment prod 153483
+```
+
 ## Clone
 
 Clone a case from one environment to another. Useful for copying production cases to development environment for testing.

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/case/commands.py

@@ -25,6 +25,19 @@ def parse_string_to_dict(input_string: str | None, delimiter: str) -> dict:
     return {key.strip(): value.strip() for key, value in valid_pairs}
 
 
+def parse_entry_id(entry_id: str) -> int:
+    """Extract the numeric case ID from a full entry ID of the form '<n>@<case-id>'.
+
+    Raises ValueError if the entry ID is not in that form.
+    """
+    parts = entry_id.split("@")
+    expected_parts = 2
+    if len(parts) != expected_parts or not parts[0].isdigit() or not parts[1].isdigit():
+        msg = f"invalid entry id '{entry_id}', expected the form <n>@<case-id> (e.g. 112@153483)"
+        raise ValueError(msg)
+    return int(parts[1])
+
+
 @click.group()
 def case() -> None:
     """Create, retrieve, and clone cases"""
@@ -210,6 +223,99 @@ def create(  # noqa: PLR0913
     click.echo(f"Created XSOAR case {case_id}")
 
 
+@click.command(name="get-context")
+@click.argument("casenumber", type=int)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_context(ctx: click.Context, casenumber: int, environment: str | None) -> None:
+    """Retrieve the investigation context tree for a single case.
+
+    CASENUMBER is the numeric case ID to look up. Output is the raw context
+    tree as JSON, matching demisto.context() at runtime.
+
+    Usage examples:
+
+    xsoar-cli case get-context 153483
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_context(casenumber)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.command(name="get-entry")
+@click.argument("entry_id", type=str)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_entry(ctx: click.Context, entry_id: str, environment: str | None) -> None:
+    """Retrieve a single War Room entry by its full ID.
+
+    ENTRY_ID is the full entry ID as shown in the GUI, in the form
+    <n>@<case-id> (e.g. 112@153483). The case ID is taken from the entry ID, so
+    it does not need to be supplied separately. Output is the raw entry as JSON.
+
+    Usage examples:
+
+    xsoar-cli case get-entry 112@153483
+    """
+    try:
+        casenumber = parse_entry_id(entry_id)
+    except ValueError as ex:
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_entry(casenumber, entry_id)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    except ValueError as ex:
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.command(name="get-entries")
+@click.argument("casenumber", type=int)
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def get_entries(ctx: click.Context, casenumber: int, environment: str | None) -> None:
+    """Retrieve all War Room entries for a single case.
+
+    CASENUMBER is the numeric case ID. Output is the full list of entries as a
+    JSON array, or an empty array when the case has no entries.
+
+    Usage examples:
+
+    xsoar-cli case get-entries 153483
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    try:
+        response = xsoar_client.cases.get_entries(casenumber)
+    except HTTPError as ex:
+        handler = HTTPErrorHandler()
+        click.echo(f"Error: {handler.get_message(ex, context='case')}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
 case.add_command(get)
 case.add_command(clone)
 case.add_command(create)
+case.add_command(get_context)
+case.add_command(get_entry)
+case.add_command(get_entries)

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/content/README.md

@@ -4,42 +4,70 @@ Inspect and manage content items on your XSOAR server.
 
 ## Get Detached
 
-List detached content items. Detached items are content items that are not associated with any installed content pack. Output is JSON formatted with 4-space indentation.
+List detached content items. Detached items are content items that have been modified on the server and are no longer in sync with the installed content pack.
+
+The output is a human-readable summary: a count followed by one line per item in the form `<name> (ID: <id>)`. When no detached items are found, the output is `No detached <type> found` (for example `No detached scripts found`). This applies to both `--type scripts` and `--type playbooks`.
 
 **Syntax:** `xsoar-cli content get-detached [OPTIONS]`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
-- `--type [scripts|playbooks|all]` - Type of content items to retrieve (default: all)
+- `--type [scripts|playbooks|all]` - Type of content items to retrieve (required)
 
 **Examples:**
 ```
-xsoar-cli content get-detached
-xsoar-cli content get-detached --environment prod
 xsoar-cli content get-detached --type scripts
-xsoar-cli content get-detached --type playbooks --environment dev
+xsoar-cli content get-detached --type playbooks
+xsoar-cli content get-detached --type all
+xsoar-cli content get-detached --type scripts --environment prod
 ```
 
 ## List
 
-List available content items. Enumerates commands, playbooks and scripts available on the server. Output is JSON formatted with 4-space indentation.
+List available content items. Enumerates commands, playbooks and scripts available on the server. Designed for discovery: a quick, scannable overview of what content exists, primarily to help humans and AI agents identify relevant items before working with them.
+
+By default the output is a human-readable table. Use `--output-format json` for machine-readable output, or `--output-format plain` for tab-separated values that are easy to pipe to tools like `grep`.
 
 **Syntax:** `xsoar-cli content list [OPTIONS]`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
 - `--type [scripts|playbooks|commands|all]` - Type of content items to list (default: all)
-- `--detail-level [short|extended|full]` - Amount of detail in the output (default: short)
+- `--search TEXT` - Case-insensitive substring filter on item id, name, and description
+- `--output-format [table|json|plain]` - Output format (default: table)
 
 **Examples:**
 ```
 xsoar-cli content list
 xsoar-cli content list --environment prod
 xsoar-cli content list --type commands
-xsoar-cli content list --type commands --detail-level extended
+xsoar-cli content list --type commands --search slack
+xsoar-cli content list --type commands --output-format json
+xsoar-cli content list --type scripts --output-format plain
 xsoar-cli content list --type playbooks --environment dev
 ```
 
+## Describe
+
+Describe a single content item in detail. Looks up one script, playbook, or command by name and shows its description, arguments, and inputs/outputs. Commands also show the integration brand and its configured instances (name and state). Use this after `content list` to get the detail needed to actually use an item.
+
+The lookup is case-insensitive. Scripts match on id, playbooks match on id or name (so a custom playbook with a UUID id resolves by its human-readable name), and commands match on the command name.
+
+**Syntax:** `xsoar-cli content describe --type TYPE NAME`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--type [script|playbook|command]` - Type of content item to describe (required)
+- `--output-format [table|json]` - Output format (default: table)
+
+**Examples:**
+```
+xsoar-cli content describe --type command servicenow-get-record
+xsoar-cli content describe --type script AddDNBHostIndicatorToCase
+xsoar-cli content describe --type playbook "Phishing Investigation - Generic v2"
+xsoar-cli content describe --type command servicenow-get-record --output-format json
+```
+
 ## Download
 
 Download a content item by name from the XSOAR server.

{xsoar_cli-2.3.0 → xsoar_cli-2.4.1}/src/xsoar_cli/commands/content/commands.py

@@ -1,4 +1,3 @@
-import json
 import logging
 import pathlib
 import subprocess
@@ -7,8 +6,9 @@ from typing import TYPE_CHECKING
 import click
 
 from xsoar_cli.utilities.config_file import get_xsoar_config, load_config
-from xsoar_cli.utilities.content import DETAIL_LEVELS, filter_content
+from xsoar_cli.utilities.content import describe_item, filter_content, format_detached_summary, search_content
 from xsoar_cli.utilities.download_content_handlers import HANDLERS, resolve_output_path
+from xsoar_cli.utilities.output import DESCRIBE_OUTPUT_FORMATS, OUTPUT_FORMATS, format_content_output, format_describe
 from xsoar_cli.utilities.validators import validate_xsoar_connectivity
 
 if TYPE_CHECKING:
@@ -28,7 +28,7 @@ def content() -> None:
 @click.option(
     "--type",
     "content_type",
-    type=click.Choice(["scripts", "playbooks"], case_sensitive=False),
+    type=click.Choice(["scripts", "playbooks", "all"], case_sensitive=False),
     required=True,
     help="Type of content items to retrieve.",
 )
@@ -39,9 +39,13 @@ def get_detached(ctx: click.Context, environment: str | None, content_type: str)
     """List detached content items."""
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
-    response = xsoar_client.content.get_detached(content_type)
-    data = json.loads(response)
-    click.echo(json.dumps(data, indent=4))
+
+    types = ["scripts", "playbooks"] if content_type == "all" else [content_type]
+    sections = []
+    for t in types:
+        items = xsoar_client.content.get_detached(t)
+        sections.append(format_detached_summary(items, t))
+    click.echo("\n\n".join(sections))
 
 
 # We name the command in the decorator here to avoid shadowing the builtin list.
@@ -56,16 +60,21 @@ def get_detached(ctx: click.Context, environment: str | None, content_type: str)
     help="Type of content items to list.",
 )
 @click.option(
-    "--detail-level",
-    type=click.Choice(DETAIL_LEVELS, case_sensitive=False),
-    default="short",
+    "--search",
+    default=None,
+    help="Case-insensitive substring filter on item id, name, and description.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(OUTPUT_FORMATS, case_sensitive=False),
+    default="table",
     show_default=True,
-    help="Amount of detail to include in the output.",
+    help="Output format. Use 'json' for machine-readable output.",
 )
 @click.pass_context
 @load_config
 @validate_xsoar_connectivity
-def list_content(ctx: click.Context, environment: str | None, content_type: str, detail_level: str) -> None:
+def list_content(ctx: click.Context, environment: str | None, content_type: str, search: str | None, output_format: str) -> None:
     """
     List available content items. Enumerates commands, playbooks and scripts
     available on the server, primarily to facilitate better AI generated
@@ -73,16 +82,59 @@ def list_content(ctx: click.Context, environment: str | None, content_type: str,
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
     json_blob = xsoar_client.content.list(content_type)
-    if detail_level == "full":
-        click.echo(json.dumps(json_blob, indent=4))
-        ctx.exit(0)
 
     # Individual type calls return a bare list, normalize to dict for filter_content.
     if isinstance(json_blob, list):
         json_blob = {content_type: json_blob}
 
-    filtered = filter_content(json_blob, detail_level=detail_level)
-    click.echo(json.dumps(filtered, indent=4))
+    filtered = filter_content(json_blob)
+    if search:
+        filtered = search_content(filtered, search)
+        if not filtered:
+            click.echo(f"No content matching '{search}' found.")
+            return
+
+    click.echo(format_content_output(filtered, output_format=output_format))
+
+
+@click.command()
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option(
+    "--type",
+    "content_type",
+    type=click.Choice(["script", "playbook", "command"], case_sensitive=False),
+    required=True,
+    help="Type of content item to describe.",
+)
+@click.option(
+    "--output-format",
+    type=click.Choice(DESCRIBE_OUTPUT_FORMATS, case_sensitive=False),
+    default="table",
+    show_default=True,
+    help="Output format. Use 'json' for machine-readable output.",
+)
+@click.argument("name", type=str)
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def describe(ctx: click.Context, environment: str | None, content_type: str, output_format: str, name: str) -> None:
+    """Describe a single content item in detail.
+
+    Looks up one script, playbook, or command by name and shows its
+    description, arguments, and inputs/outputs. Commands also show the
+    integration brand and its configured instances. Use this after
+    'content list' to get the detail needed to actually use an item.
+    """
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    raw = xsoar_client.content.describe(content_type, name)
+    if raw is None:
+        click.echo(f"Error: {content_type} '{name}' not found")
+        ctx.exit(1)
+        return
+
+    item = describe_item(content_type, raw)
+    click.echo(format_describe(content_type, item, output_format=output_format))
 
 
 @click.command()
@@ -175,4 +227,5 @@ def download(ctx: click.Context, environment: str | None, content_type: str, out
 
 content.add_command(get_detached)
 content.add_command(list_content)
+content.add_command(describe)
 content.add_command(download)