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

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

@@ -8,6 +8,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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.3.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.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.2.0
+Version: 2.3.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.3.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.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)
 
 __commit_id__ = commit_id = None

{xsoar_cli-2.2.0 → xsoar_cli-2.3.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.3.0}/src/xsoar_cli/commands/content/README.md

@@ -29,12 +29,14 @@ List available content items. Enumerates commands, playbooks and scripts availab
 **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)
 
 **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 playbooks --environment dev
 ```
 

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

@@ -7,7 +7,7 @@ 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 DETAIL_LEVELS, filter_content
 from xsoar_cli.utilities.download_content_handlers import HANDLERS, resolve_output_path
 from xsoar_cli.utilities.validators import validate_xsoar_connectivity
 
@@ -55,19 +55,25 @@ 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(
+    "--detail-level",
+    type=click.Choice(DETAIL_LEVELS, case_sensitive=False),
+    default="short",
+    show_default=True,
+    help="Amount of detail to include in the 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, detail_level: 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:
+    if detail_level == "full":
         click.echo(json.dumps(json_blob, indent=4))
         ctx.exit(0)
 
@@ -75,7 +81,7 @@ def list_content(ctx: click.Context, environment: str | None, content_type: str,
     if isinstance(json_blob, list):
         json_blob = {content_type: json_blob}
 
-    filtered = filter_content(json_blob, detail=detail)
+    filtered = filter_content(json_blob, detail_level=detail_level)
     click.echo(json.dumps(filtered, indent=4))
 
 

xsoar_cli-2.3.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
+```

xsoar_cli-2.3.0/src/xsoar_cli/commands/execute/commands.py

@@ -0,0 +1,337 @@
+import logging
+from typing import TYPE_CHECKING
+
+import click
+
+from xsoar_cli.utilities.config_file import get_xsoar_config, load_config
+from xsoar_cli.utilities.validators import validate_xsoar_connectivity
+from xsoar_cli.xsoar_client.execution import DEFAULT_SYNC_TIMEOUT, EXECUTION_MODES
+
+if TYPE_CHECKING:
+    from xsoar_cli.xsoar_client.client import Client
+
+logger = logging.getLogger(__name__)
+
+# XSOAR entry type identifying an error entry in command output.
+ERROR_ENTRY_TYPE = 4
+
+
+def parse_arg_tokens(tokens: tuple[str, ...]) -> dict[str, str]:
+    """Parse variadic key=value tokens into a dictionary.
+
+    Raises ValueError on any token that does not contain a "=" separator.
+    """
+    args: dict[str, str] = {}
+    for token in tokens:
+        if "=" not in token:
+            msg = f"Malformed argument '{token}'. Arguments must be on the form key=value."
+            raise ValueError(msg)
+        key, value = token.split("=", 1)
+        args[key.strip()] = value.strip()
+    return args
+
+
+def resolve_investigation_id(ctx: click.Context, xsoar_client: "Client", case_id: int | None) -> str:
+    """Return the target investigation ID.
+
+    Uses the supplied case ID when present, otherwise resolves the user's
+    playground investigation ID.
+
+    Distinguishes two failure modes when resolving the playground:
+
+    * ApiException means the XSOAR API call itself failed (connectivity, auth,
+      server error). The user is pointed at the environment.
+    * RuntimeError means the calls succeeded but no single playground could be
+      identified. The specific reason is surfaced to the user.
+
+    Both cases print a message and exit with a non-zero status.
+    """
+    # Lazy import for performance reasons
+    from demisto_client.demisto_api.rest import ApiException
+
+    if case_id is not None:
+        logger.debug("Using supplied case ID %d as investigation ID", case_id)
+        return str(case_id)
+
+    logger.debug("No case ID supplied, resolving user's playground investigation ID")
+    try:
+        investigation_id = xsoar_client.execution.resolve_playground_id()
+    except ApiException as ex:
+        logger.info("Playground lookup failed with API error: %s", ex)
+        click.echo(f"Error: failed to query XSOAR for the playground investigation: {ex}")
+        ctx.exit(1)
+    except RuntimeError as ex:
+        logger.info("Could not resolve playground investigation: %s", ex)
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+    logger.debug("Resolved playground investigation ID: %s", investigation_id)
+    return investigation_id
+
+
+def build_entry_url(server_url: str, view: str, segment: str, entry_id: str) -> str:
+    """Build a direct link to an entry in a given XSOAR view.
+
+    The URL shape is <server_url>/#/<view>/<segment>/<entry_id>, where view is
+    "WarRoom" or "artifactViewer" and segment is the literal "playground" for
+    playground executions or the case ID for a case. The server URL's trailing
+    slash, if any, is stripped.
+    """
+    base = server_url.rstrip("/")
+    return f"{base}/#/{view}/{segment}/{entry_id}"
+
+
+def _result_entry_lines(entry_id: str, server_url: str, segment: str) -> list[str]:
+    """Build the grouped output lines for a single result entry.
+
+    Each result entry is shown with a short header and two links: the War Room
+    view for context and the artifact viewer for downloading the entry content.
+    The short entry number (the part before "@") is used in the header for
+    readability; the full id is preserved in the URLs.
+    """
+    short_id = entry_id.split("@", 1)[0]
+    return [
+        f"Entry {short_id}:",
+        f"  War Room entry: {build_entry_url(server_url, 'WarRoom', segment, entry_id)}",
+        f"  Artifact viewer: {build_entry_url(server_url, 'artifactViewer', segment, entry_id)}",
+    ]
+
+
+def render_command_output(
+    result: dict,
+    name: str,
+    server_url: str,
+    warroom_segment: str,
+) -> tuple[str, bool]:
+    """Render an execute-command result for display.
+
+    Returns a (text, had_error) tuple. had_error is True when the command
+    returned one or more error entries, so the caller can exit non-zero.
+
+    Reports only what is known:
+
+    * sync success: that the command completed, the entry count, and War Room
+      and artifact viewer links per returned entry.
+    * sync error: the contents of each error entry and links to it.
+    * sync timeout: that no results arrived in time and the command may still
+      be running, with a War Room link to the submitted entry.
+    * async: that the command was submitted, with the created entry ID and a
+      War Room link.
+    """
+    if "entries" in result:
+        if result.get("timed_out"):
+            return _render_timeout_summary(result, server_url, warroom_segment), False
+        return _render_sync_summary(result["entries"], name, server_url, warroom_segment)
+    return _render_async_summary(result.get("entry", {}), name, server_url, warroom_segment), False
+
+
+def _render_sync_summary(entries: list[dict], name: str, server_url: str, warroom_segment: str) -> tuple[str, bool]:
+    """Render the summary for a synchronous (blocking) command execution.
+
+    Each result entry is shown grouped with its War Room and artifact viewer
+    links, separated by a blank line for readability.
+    """
+    error_entries = [entry for entry in entries if entry.get("type") == ERROR_ENTRY_TYPE]
+
+    if error_entries:
+        total = len(entries)
+        error_count = len(error_entries)
+        total_plural = "entry" if total == 1 else "entries"
+        error_plural = "error" if error_count == 1 else "errors"
+        lines = [f"Command {name} completed with errors ({total} {total_plural}, {error_count} {error_plural})."]
+        for entry in error_entries:
+            entry_id = entry.get("id", "")
+            if not entry_id:
+                continue
+            lines.append("")
+            contents = entry.get("contents")
+            if contents:
+                lines.append(str(contents))
+            lines.extend(_result_entry_lines(entry_id, server_url, warroom_segment))
+        return "\n".join(lines), True
+
+    count = len(entries)
+    plural = "entry" if count == 1 else "entries"
+    lines = [f"Command {name} completed ({count} {plural})."]
+    for entry in entries:
+        entry_id = entry.get("id", "")
+        if not entry_id:
+            continue
+        lines.append("")
+        lines.extend(_result_entry_lines(entry_id, server_url, warroom_segment))
+    return "\n".join(lines), False
+
+
+def _render_timeout_summary(result: dict, server_url: str, warroom_segment: str) -> str:
+    """Render the summary when a sync command produced no results before timeout.
+
+    A timeout is treated as success with a warning: the command was submitted
+    successfully (a submit failure surfaces fast as an API error), so it is
+    almost certainly still running. The link points at the submitted entry.
+    """
+    entry_id = result.get("entry_id", "")
+    lines = ["No command results within timeout. It may still be running."]
+    if entry_id:
+        lines.append(f"War Room entry: {build_entry_url(server_url, 'WarRoom', warroom_segment, entry_id)}")
+    return "\n".join(lines)
+
+
+def _render_async_summary(entry: dict, name: str, server_url: str, warroom_segment: str) -> str:
+    """Render the summary for an asynchronous command submission."""
+    entry_id = entry.get("id", "")
+    lines = [f"Command {name} submitted. Entry ID: {entry_id}"]
+    if entry_id:
+        lines.append(f"War Room entry: {build_entry_url(server_url, 'WarRoom', warroom_segment, entry_id)}")
+    return "\n".join(lines)
+
+
+@click.group()
+def execute() -> None:
+    """Execute scripts, integration commands, and playbooks"""
+    pass
+
+
+@click.command()
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option("--case-id", type=int, default=None, help="Case ID to execute against. Defaults to the user's playground.")
+@click.option(
+    "--mode",
+    type=click.Choice(EXECUTION_MODES, case_sensitive=False),
+    default="sync",
+    show_default=True,
+    help="Execute synchronously (wait for and return results) or asynchronously (submit and return the entry).",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=DEFAULT_SYNC_TIMEOUT,
+    show_default=True,
+    help="Seconds to wait for results in sync mode before reporting the command is still running.",
+)
+@click.argument("name", type=str)
+@click.argument("args", nargs=-1, type=str)
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def command(  # noqa: PLR0913
+    ctx: click.Context,
+    environment: str | None,
+    case_id: int | None,
+    mode: str,
+    timeout: int,
+    name: str,
+    args: tuple[str, ...],
+) -> None:
+    """Execute an automation script or integration command.
+
+    NAME is the script or integration command to run. There is no difference in
+    how scripts and integration commands are invoked. Use the bare name (as 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.
+
+    Shell note: interactive shells treat characters like "!" and "|" specially.
+    Prefer omitting the "!" and wrap argument values in single quotes when they
+    contain shell metacharacters, for example query='index=foo | head 1'.
+
+    By default execution happens in the user's playground. Pass --case-id to run
+    against a specific case instead.
+
+    --mode sync waits for the command to finish and returns the resulting War
+    Room entries. --mode async submits the command and returns immediately with
+    the created entry.
+
+    In sync mode, --timeout bounds how long to wait for results. If the command
+    has not produced results by then, it is reported as still running and a War
+    Room link is printed; this is not treated as an error.
+
+    Usage 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
+    """
+    # Lazy import for performance reasons
+    from demisto_client.demisto_api.rest import ApiException
+
+    try:
+        parsed_args = parse_arg_tokens(args)
+    except ValueError as ex:
+        click.echo(f"Error: {ex}")
+        ctx.exit(1)
+
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    investigation_id = resolve_investigation_id(ctx, xsoar_client, case_id)
+    # The War Room URL uses the literal "playground" segment for playground
+    # executions, and the case ID when running against a specific case.
+    warroom_segment = str(case_id) if case_id is not None else "playground"
+    # The leading "!" is optional on input; strip it for display so user-facing
+    # messages read the same whether or not the user included it.
+    display_name = name[1:] if name.startswith("!") else name
+    logger.info("Executing command '%s' (mode=%s) against investigation '%s'", name, mode, investigation_id)
+    if mode == "sync":
+        click.echo(f"Executing {display_name}, waiting up to {timeout}s for results...", err=True)
+    try:
+        result = xsoar_client.execution.execute_command(name, parsed_args, investigation_id, mode=mode, timeout=timeout)
+    except ApiException as ex:
+        logger.info("Command execution failed with API error: %s", ex)
+        click.echo(f"Error: command execution failed: {ex}")
+        ctx.exit(1)
+    output, had_error = render_command_output(result, display_name, xsoar_client.server_url, warroom_segment)
+    click.echo(output)
+    if had_error:
+        ctx.exit(1)
+
+
+@click.command()
+@click.option("--environment", default=None, help="Default environment set in config file.")
+@click.option("--case-id", type=int, default=None, help="Case ID to execute against. Defaults to the user's playground.")
+@click.argument("name", type=str)
+@click.pass_context
+@load_config
+@validate_xsoar_connectivity
+def playbook(ctx: click.Context, environment: str | None, case_id: int | None, name: str) -> None:
+    """Start a playbook.
+
+    NAME is the playbook to run.
+
+    By default the playbook is started in the user's playground. Pass --case-id
+    to start it in a specific case instead.
+
+    This is fire-and-forget: the playbook is started and the command returns
+    without waiting for it to finish.
+
+    Usage examples:
+
+    xsoar-cli execute playbook "My Playbook"
+
+    xsoar-cli execute playbook "My Playbook" --case-id 12345
+    """
+    # Lazy import for performance reasons
+    from demisto_client.demisto_api.rest import ApiException
+
+    config = get_xsoar_config(ctx)
+    xsoar_client: Client = config.get_client(environment)
+    investigation_id = resolve_investigation_id(ctx, xsoar_client, case_id)
+    target = f"case {case_id}" if case_id is not None else "playground"
+    logger.info("Starting playbook '%s' in %s (investigation '%s')", name, target, investigation_id)
+    try:
+        xsoar_client.execution.execute_playbook(name, investigation_id)
+    except ValueError as ex:
+        logger.info("Could not start playbook: %s", ex)
+        click.echo(f"Error: {ex}", err=True)
+        ctx.exit(1)
+    except ApiException as ex:
+        logger.info("Playbook start failed with API error: %s", ex)
+        click.echo(f"Error: failed to start playbook: {ex}", err=True)
+        ctx.exit(1)
+    click.echo(f"Started playbook {name} in {target}")
+
+
+execute.add_command(command)
+execute.add_command(playbook)

{xsoar_cli-2.2.0 → xsoar_cli-2.3.0}/src/xsoar_cli/commands/manifest/README.md

@@ -23,11 +23,13 @@ xsoar-cli manifest generate --environment prod
 
 Validate manifest JSON syntax and verify all specified content packs are available. Tests connectivity to pack sources and checks local pack metadata for development packs.
 
+By default, all packs in the manifest are validated. Use `--only-changed` to limit validation to packs whose version differs from what is currently installed on the server. This is useful in CI pipelines where only a few packs change per PR.
+
 **Syntax:** `xsoar-cli manifest validate [OPTIONS] MANIFEST_PATH`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
-- `--mode [full|diff]` - Validate the full manifest, or only the definitions that diff with installed versions (default: diff)
+- `--only-changed` - Only validate packs that differ from what is currently installed on the server
 
 **Arguments:**
 - `MANIFEST_PATH` - Path to the manifest file to validate
@@ -35,6 +37,7 @@ Validate manifest JSON syntax and verify all specified content packs are availab
 **Examples:**
 ```
 xsoar-cli manifest validate ./xsoar_config.json
+xsoar-cli manifest validate --only-changed ./xsoar_config.json
 xsoar-cli manifest validate --environment staging ./xsoar_config.json
 ```