xsoar-cli 2.2.0__tar.gz → 2.4.0__tar.gz

{xsoar_cli-2.2.0 → xsoar_cli-2.4.0}/CHANGELOG.md

@@ -8,6 +8,53 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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.
+
+### 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.
+- `execute playbook NAME` starts a playbook in the user's playground, or a specific case with `--case-id`. See the [execute README](src/xsoar_cli/commands/execute/README.md) for details.
+
+### Fixed
+
+- `content download` now correctly resolves playbooks whose ID differs from their name when the name contains spaces. Previously, the name search query was not quoted, causing it to return no results. In practice this affected custom playbooks created in the XSOAR UI, which use a UUID as their ID.
+
+### Changed
+
+- **Breaking:** `manifest validate` now validates all packs by default (previously defaulted to `--mode diff`). Use the new `--only-changed` flag to validate only packs that differ from what is installed on the server.
+- **Breaking:** `content list` now uses a single `--detail-level` option (choices: `short`, `extended`, `full`, default: `short`) instead of the separate `--details` and `--verbose` flags.
+- Plugin commands are now listed under a separate `Plugins:` section in `--help` output instead of being mixed with core commands.
+
+### Removed
+
+- `manifest validate --mode` option. Use `--only-changed` instead of `--mode diff`. Full validation is now the default.
+- `content list --details` flag. Use `--detail-level extended` instead.
+- `content list --verbose` flag. Use `--detail-level full` instead.
+
+## [2.2.0] - 2026-04-10
+
+### Added
+
 - `config set-version-check` command to enable or disable the version update check on CLI startup. Accepts `--enable` or `--disable`.
 - `plugins init` command to create the plugins directory and generate an example plugin.
 

{xsoar_cli-2.2.0 → xsoar_cli-2.4.0}/CLAUDE.md

@@ -28,7 +28,7 @@ for confirmation before executing any terminal commands as they may have consequ
 - **Build System**: Hatchling (`pyproject.toml`)
 - **Package Manager**: uv (`uv.lock`)
 - **Linting**: Ruff
-- **Formatting**: Black
+- **Formatting**: Ruff formatter (>99.9% Black-compatible)
 - **Testing**: pytest, pytest-cov
 - **CI**: GitHub Actions (Python 3.10-3.14)
 
@@ -142,10 +142,10 @@ uv run pytest tests/cli/
 uv run pytest tests/unit/
 
 # Format code
-black src/ tests/
+uv run ruff format src/ tests/
 
 # Lint
-ruff check src/ tests/
+uv run ruff check src/ tests/
 
 # Run the CLI
 uv run xsoar-cli --help
@@ -206,9 +206,11 @@ The user's live configuration at `~/.config/xsoar-cli/config.json` contains API
 
 ## Changelog
 
+**Every PR that changes user-facing behavior MUST include a `CHANGELOG.md` update. Do not treat this as optional or as a follow-up step. The changelog entry is part of the implementation, not separate from it.**
+
 - The project maintains a `CHANGELOG.md` in the repository root.
 - The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
-- All user-facing changes must be documented in `CHANGELOG.md`. This includes:
+- Changes that require a changelog entry:
   - Adding, removing, or renaming commands, options, or arguments (`Added` / `Removed`)
   - Changes to default behavior or output format (`Changed`)
   - Bug fixes (`Fixed`)

{xsoar_cli-2.2.0 → xsoar_cli-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.2.0
+Version: 2.4.0
 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.2.0 → xsoar_cli-2.4.0}/_version.py

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

{xsoar_cli-2.2.0 → xsoar_cli-2.4.0}/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.2.0 → xsoar_cli-2.4.0}/src/xsoar_cli/cli.py

@@ -17,6 +17,7 @@ from .commands.case import commands as case_commands
 from .commands.completions import commands as completions_commands
 from .commands.config import commands as config_commands
 from .commands.content import commands as content_commands
+from .commands.execute import commands as execute_commands
 from .commands.graph import commands as graph_commands
 from .commands.integration import commands as integration_commands
 from .commands.manifest import commands as manifest_commands
@@ -30,12 +31,46 @@ from .utilities.version_check import check_for_update
 
 
 class XSOARCliGroup(click.Group):
-    """Custom Click group that surfaces plugin load failures when a command is not found.
+    """Custom Click group with separate help sections for core and plugin commands.
 
-    Without this, a failed plugin silently disappears and the user gets a generic
-    "No such command" error with no indication that a plugin was involved.
+    Also surfaces plugin load failures when a command is not found, so the user
+    does not get a generic "No such command" error with no indication that a
+    plugin was involved.
     """
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.core_commands: set[str] = set()
+
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        """Format help output with core commands and plugin commands in separate sections."""
+        core_rows = []
+        plugin_rows = []
+
+        for subcommand in self.list_commands(ctx):
+            cmd = self.get_command(ctx, subcommand)
+            if cmd is None or cmd.hidden:
+                continue
+            target = core_rows if subcommand in self.core_commands else plugin_rows
+            target.append((subcommand, cmd))
+
+        if not core_rows and not plugin_rows:
+            return
+
+        all_names = core_rows + plugin_rows
+        limit = formatter.width - 6 - max(len(name) for name, _ in all_names)
+
+        def make_rows(commands):
+            return [(name, cmd.get_short_help_str(limit)) for name, cmd in commands]
+
+        if core_rows:
+            with formatter.section("Commands"):
+                formatter.write_dl(make_rows(core_rows))
+
+        if plugin_rows:
+            with formatter.section("Plugins"):
+                formatter.write_dl(make_rows(plugin_rows))
+
     def resolve_command(self, ctx: click.Context, args: list) -> tuple:
         try:
             return super().resolve_command(ctx, args)
@@ -70,6 +105,7 @@ def _register_commands() -> None:
     cli.add_command(config_commands.config)
     cli.add_command(content_commands.content)
 
+    cli.add_command(execute_commands.execute)
     cli.add_command(graph_commands.graph)
     cli.add_command(integration_commands.integration)
     cli.add_command(manifest_commands.manifest)
@@ -129,6 +165,7 @@ def _configure_logging(config_data: dict | None) -> LoggingSetup:
 # "Exit:" entries for pytest invocations.
 _register_commands()
 CORE_COMMANDS, plugin_manager = _load_plugins()
+cli.core_commands = set(CORE_COMMANDS)
 
 # Initialized in main(). None when the module is imported without calling main(),
 # which is the case during test runs.

{xsoar_cli-2.2.0 → xsoar_cli-2.4.0}/src/xsoar_cli/commands/content/README.md

@@ -4,40 +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)
+- `--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 --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.2.0 → xsoar_cli-2.4.0}/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 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.
@@ -55,28 +59,82 @@ def get_detached(ctx: click.Context, environment: str | None, content_type: str)
     show_default=True,
     help="Type of content items to list.",
 )
-@click.option("--detail", is_flag=True, default=False, help="Include argument-level detail in filtered output.")
-@click.option("--verbose", is_flag=True, default=False, help="Output the full unfiltered response.")
+@click.option(
+    "--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="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: bool, verbose: bool) -> None:
+def list_content(ctx: click.Context, environment: str | None, content_type: str, search: str | None, output_format: str) -> None:
     """
-    List detached content items. The purpose of this function is to list out available commands,
-    playbooks and scripts, primarily to facilitate better AI generated playbooks"""
+    List available content items. Enumerates commands, playbooks and scripts
+    available on the server, primarily to facilitate better AI generated
+    playbooks."""
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
     json_blob = xsoar_client.content.list(content_type)
-    if verbose:
-        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=detail)
-    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()
@@ -169,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)

xsoar_cli-2.4.0/src/xsoar_cli/commands/execute/README.md

@@ -0,0 +1,67 @@
+# Execute
+
+Execute scripts, integration commands, and playbooks against an XSOAR investigation.
+
+By default, execution happens in the user's playground. Pass `--case-id` to run against a specific case instead.
+
+## Command
+
+Execute an automation script or integration command. There is no difference in how scripts and integration commands are invoked.
+
+Use the bare command or script name, the same way you would reference it in a playbook. A leading `!` is accepted but optional.
+
+Arguments are supplied as space-separated `key=value` pairs. Values containing whitespace are quoted automatically. A malformed argument (one without a `=`) causes the command to exit with an error.
+
+**Shell note:** interactive shells (zsh, bash) treat characters like `!` and `|` specially. Prefer omitting the `!`, and wrap argument values in single quotes when they contain shell metacharacters, for example `query='index=zscaler | head 1'`.
+
+**Syntax:** `xsoar-cli execute command [OPTIONS] NAME [ARGS]...`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--case-id INTEGER` - Case ID to execute against (default: the user's playground)
+- `--mode [sync|async]` - Wait for results (`sync`) or submit and return the created entry (`async`) (default: "sync")
+- `--timeout INTEGER` - Seconds to wait for results in sync mode before reporting the command is still running (default: 30)
+
+**Arguments:**
+- `NAME` - The script or integration command to run
+- `ARGS` - Zero or more `key=value` argument pairs
+
+**Output:**
+
+On success, prints a completion line with the entry count, then for each resulting entry a short `Entry <id>:` header followed by two links: a War Room link (to view the entry in context) and an artifact viewer link (which offers a direct download of the entry content in XSOAR). The entry contents are not printed. If a command produces an error entry, the error contents are printed alongside its links and the command exits non-zero.
+
+In sync mode, the command submits the request and then polls for the resulting War Room entries. If no results appear within `--timeout` seconds, the command is reported as still running with a War Room link to the submitted entry, and the exit code stays zero. A failed submission surfaces immediately as an error with a non-zero exit code.
+
+**Examples:**
+```
+xsoar-cli execute command MyScript arg1=val1 arg2=val2
+xsoar-cli execute command whois query=example.com --case-id 12345
+xsoar-cli execute command splunk-search query='index=zscaler | head 1'
+xsoar-cli execute command MyScript arg1=val1 --mode async
+xsoar-cli execute command LongRunningScript --timeout 60
+```
+
+## Playbook
+
+Start a playbook in the playground or a specific case. The playbook name is resolved to its ID before starting, so the display name works even for custom playbooks whose ID is a UUID.
+
+This is fire-and-forget: the playbook is started via the `setPlaybook` command and the CLI returns without waiting for the playbook to finish. Follow up in the XSOAR War Room to see its progress.
+
+**Syntax:** `xsoar-cli execute playbook [OPTIONS] NAME`
+
+**Options:**
+- `--environment TEXT` - Target environment (default: uses default environment from config)
+- `--case-id INTEGER` - Case ID to start the playbook in (default: the user's playground)
+
+**Arguments:**
+- `NAME` - The playbook to start
+
+**Output:**
+
+Prints `Started playbook <name> in playground` or `Started playbook <name> in case <id>`. If the playbook name cannot be found, the command exits non-zero with an error.
+
+**Examples:**
+```
+xsoar-cli execute playbook "My Playbook"
+xsoar-cli execute playbook "My Playbook" --case-id 12345
+```