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

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

@@ -6,6 +6,54 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### 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.
+
+### Changed
+
+- **Breaking:** Plugins must explicitly import `XSOARPlugin` (`from xsoar_cli.plugins import XSOARPlugin`). The base class is no longer injected automatically and so old plugins require modification. See the [plugin README](src/xsoar_cli/plugins/README.md) for details.
+- Plugin commands (`list`, `info`, `validate`) now report a clear error when the plugins directory has not been initialized.
+- Plugin registration failures no longer prevent remaining plugins from loading.
+- `content get-detached --type` is now required. The `all` choice has been removed; specify `scripts` or `playbooks` explicitly.
+- `integration dump`, `rbac getroles`, `rbac getusers`, and `rbac getusergroups` no longer emit a trailing blank line after JSON output.
+- `config show` now uses `click.echo()` instead of `print()`, improving behavior when piping output to other tools.
+
+### Removed
+
+- The plugins directory is no longer automatically created on CLI startup. Run `xsoar-cli plugins init` to create it explicitly.
+
+### Fixed
+
+- `content get-detached` no longer fails when invoked without `--type` due to a stale default value that referenced the removed `all` choice.
+- Content bundle download (`get_content_bundle`) now raises on HTTP errors instead of silently proceeding and failing with a confusing `tarfile` error.
+
+## [2.1.1] - 2026-04-08
+
 ### Changed
 
 - `manifest generate` now uses an `--output-dir` option (default: current directory) instead of a positional path argument. The output file is always named `xsoar_config.json`. Prompts for confirmation if the file already exists.
@@ -83,4 +131,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Removed
 
-- `config validate --stacktrace` option. Use `--verbose` / `-v` instead.
+- `config validate --stacktrace` option. Use `--verbose` / `-v` instead.

{xsoar_cli-2.1.1 → 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)
 
@@ -64,6 +64,7 @@ src/xsoar_cli/            # Main package (src layout)
       azure.py            # AzureArtifactProvider (Azure Blob Storage)
   commands/               # CLI command groups
     case/                 # Case operations command group
+    completions/          # Shell autocompletion command group
     config/               # Config management command group
     content/              # Content download/list command group
     graph/                # Dependency graph command group
@@ -124,9 +125,6 @@ Always use `--no-pager` when running git commands (e.g. `git --no-pager log`, `g
 ```sh
 # Install dependencies
 uv sync
-uv pip install -r requirements.txt
-uv pip install -r requirements_dev.txt
-uv pip install -e .
 
 # Run all tests
 uv run pytest
@@ -144,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
@@ -208,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.1.1 → xsoar_cli-2.3.0}/CONTRIBUTING.md

@@ -44,40 +44,16 @@ For other platforms and installation options, see the [uv installation docs](htt
 
 ### 3. Set Up Development Environment
 
-**Recommended: uv**
-
-You may find that you will need to make modifications in [xsoar-client](https://github.com/tlium/xsoar-client) and/or [xsoar-dependency-graph](https://github.com/tlium/xsoar-dependency-graph) in order
-to fix bugs or add new features to `xsoar-cli`. If you need to work on `xsoar-client` or `xsoar-dependency-graph`, install them in editable mode from your local Git clones:
-
-```bash
-uv pip install -e /path/to/your/xsoar-client
-uv pip install -e /path/to/your/xsoar-dependency-graph
-```
-
 ```bash
 # Install dependencies and xsoar-cli in editable mode
 uv sync
 uv pip install -e .
 ```
-**Alternative: pip/venv**
 
-```bash
-# Create and activate a virtual environment
-python -m venv venv
-source venv/bin/activate
-
-# Install development dependencies
-pip install -r requirements_dev.txt
-
-# Install xsoar-cli in editable mode
-pip install -e .
-```
-
-If you need to work on the supporting libraries, install them in editable mode as well:
+You may need to make modifications in [xsoar-dependency-graph](https://github.com/tlium/xsoar-dependency-graph) to fix bugs or add new features to `xsoar-cli`. If so, install it in editable mode from your local Git clone:
 
 ```bash
-pip install -e /path/to/your/xsoar-client
-pip install -e /path/to/your/xsoar-dependency-graph
+uv pip install -e /path/to/your/xsoar-dependency-graph
 ```
 
 ## Development Workflow
@@ -115,16 +91,15 @@ pip install -e /path/to/your/xsoar-dependency-graph
 
 #### Lazy imports
 
-Heavy third-party packages like `xsoar_client`, `xsoar_dependency_graph` and `demisto_client` pull in large dependency trees (boto3, azure-storage-blob, matplotlib, networkx, etc.) that are expensive to load. To keep everyday invocations like `--help` and `--version` fast, these imports are placed inside the functions that need them rather than at the top of the file. Each lazy import is marked with the comment `# Lazy import for performance reasons`.
+Heavy third-party packages like `xsoar_dependency_graph` and `demisto_client` pull in large dependency trees (boto3, azure-storage-blob, matplotlib, networkx, etc.) that are expensive to load. To keep everyday invocations like `--help` and `--version` fast, these imports are placed inside the functions that need them rather than at the top of the file. Each lazy import is marked with the comment `# Lazy import for performance reasons`.
 
-Type hints for the deferred types still appear in function signatures. To avoid quoting them as strings, modules that use this pattern include `from __future__ import annotations` and a `TYPE_CHECKING` block at the top:
+Type hints for the deferred types still appear in function signatures. To keep them clean, use a `TYPE_CHECKING` block at the top of the module:
 
 ```python
-from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from xsoar_client.xsoar_client import Client
+    from xsoar_cli.xsoar_client.client import Client
 ```
 
 See `configuration.py` for a complete example.

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

@@ -1,6 +1,7 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.1.1
+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
 Project-URL: Source, https://github.com/tlium/xsoar-cli

{xsoar_cli-2.1.1 → 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.1.1'
-__version_tuple__ = version_tuple = (2, 1, 1)
+__version__ = version = '2.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)
 
 __commit_id__ = commit_id = None

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

@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
 [project]
 name = "xsoar-cli"
 dynamic = ["version"]
-description = ''
+description = 'A command-line interface for managing Palo Alto Networks XSOAR (Cortex XSOAR)'
 readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"

{xsoar_cli-2.1.1 → 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)
@@ -83,13 +119,29 @@ def _load_plugins() -> tuple[list[str], PluginManager]:
     """Captures core command names, then loads and registers plugins. Returns both."""
     core_commands = list(cli.commands.keys())
     manager = PluginManager()
-    try:
-        manager.load_all_plugins(ignore_errors=True)
-        for plugin_name, error in manager.get_failed_plugins().items():
-            click.echo(f"Warning: plugin '{plugin_name}' failed to load: {error}", err=True)
-        manager.register_plugin_commands(cli)
-    except Exception as e:
-        click.echo(f"Warning: failed to register plugin commands: {e}", err=True)
+
+    if not manager.plugins_dir_exists:
+        logging.getLogger(__name__).debug("Plugins directory not found, skipping plugin loading")
+        return core_commands, manager
+
+    manager.load_all_plugins(ignore_errors=True)
+
+    # Report load failures on stderr. These warnings run at module level before
+    # logging is configured, so logger.warning would be invisible. Plugin load
+    # failures are important enough to surface unconditionally.
+    load_failures = set(manager.get_failed_plugins().keys())
+    for plugin_name, error in manager.get_failed_plugins().items():
+        click.echo(f"Warning: plugin '{plugin_name}' failed to load: {error}", err=True)
+
+    manager.register_plugin_commands(cli)
+
+    # Registration failures are recorded in failed_plugins by the manager
+    # (skip-and-record pattern). Report only the new ones added during registration.
+    for plugin_name, error in manager.get_failed_plugins().items():
+        if plugin_name in load_failures:
+            continue  # Already reported above
+        click.echo(f"Warning: plugin '{plugin_name}' failed to register: {error}", err=True)
+
     return core_commands, manager
 
 
@@ -113,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.1.1 → xsoar_cli-2.3.0}/src/xsoar_cli/commands/case/commands.py

@@ -8,7 +8,10 @@ from requests.exceptions import HTTPError
 from xsoar_cli.error_handling.connection import ConnectionErrorHandler
 from xsoar_cli.error_handling.http import HTTPErrorHandler
 from xsoar_cli.utilities.config_file import get_xsoar_config, load_config
-from xsoar_cli.utilities.validators import validate_environments
+from xsoar_cli.utilities.validators import validate_environments, validate_xsoar_connectivity
+
+if TYPE_CHECKING:
+    from xsoar_cli.xsoar_client.client import Client
 
 logger = logging.getLogger(__name__)
 
@@ -22,12 +25,9 @@ def parse_string_to_dict(input_string: str | None, delimiter: str) -> dict:
     return {key.strip(): value.strip() for key, value in valid_pairs}
 
 
-if TYPE_CHECKING:
-    from xsoar_cli.xsoar_client.client import Client
-
-
-@click.group(help="Create, retrieve, and clone cases")
+@click.group()
 def case() -> None:
+    """Create, retrieve, and clone cases"""
     pass
 
 
@@ -36,6 +36,7 @@ def case() -> None:
 @click.option("--environment", default=None, help="Default environment set in config file.")
 @click.pass_context
 @load_config
+@validate_xsoar_connectivity
 def get(ctx: click.Context, casenumber: int, environment: str | None) -> None:
     """Retrieve and display a single case.
 
@@ -82,7 +83,12 @@ def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
         click.echo(f"Error: cannot find environments {source} and/or {dest} in config")
         ctx.exit(1)
 
-    # Test connectivity to both environments before proceeding
+    # Test connectivity to both environments before proceeding. This is the only function that does
+    # explicit connectivity testing and error handling due to the fact that it is the only function
+    # that operates on multiple environments. If later a new command or sub-command is added to
+    # xsoar-cli that operates on multiple environments, then a new decorator should be created to
+    # handle connectivity testing for multiple environments (@validate_xsoar_connectivity only tests
+    # a single environment)
     config = get_xsoar_config(ctx)
     for env_name in (source, dest):
         logger.debug("Testing XSOAR connectivity for environment '%s'", env_name)
@@ -159,6 +165,7 @@ def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
 @click.argument("name", type=str, default="Test case created from xsoar-cli")
 @click.pass_context
 @load_config
+@validate_xsoar_connectivity
 def create(  # noqa: PLR0913
     ctx: click.Context,
     environment: str | None,

{xsoar_cli-2.1.1 → xsoar_cli-2.3.0}/src/xsoar_cli/commands/completions/commands.py

@@ -73,8 +73,9 @@ def _resolve_shell(shell_name: str | None) -> str:
     return detected
 
 
-@click.group(help="Install and manage shell completion for xsoar-cli.")
+@click.group()
 def completions() -> None:
+    """Install and manage shell completion for xsoar-cli"""
     pass
 
 

{xsoar_cli-2.1.1 → xsoar_cli-2.3.0}/src/xsoar_cli/commands/config/README.md

@@ -101,3 +101,21 @@ Set the Azure Blob Storage SAS token for an environment in the configuration fil
 xsoar-cli config set-azure-token my-sas-token
 xsoar-cli config set-azure-token --environment prod my-sas-token
 ```
+
+## Set Version Check
+
+Enable or disable the version update check on CLI startup. When enabled, the CLI checks PyPI for newer versions and prints a notice to stderr.
+
+**Syntax:** `xsoar-cli config set-version-check [OPTIONS]`
+
+**Options:**
+- `--enable` - Enable the version update check
+- `--disable` - Disable the version update check
+
+One of `--enable` or `--disable` must be provided.
+
+**Examples:**
+```
+xsoar-cli config set-version-check --enable
+xsoar-cli config set-version-check --disable
+```

{xsoar_cli-2.1.1 → xsoar_cli-2.3.0}/src/xsoar_cli/commands/config/commands.py

@@ -5,9 +5,6 @@ from typing import TYPE_CHECKING
 
 import click
 
-if TYPE_CHECKING:
-    from xsoar_cli.xsoar_client.client import Client
-
 from xsoar_cli.utilities.config_file import (
     get_config_file_contents,
     get_config_file_path,
@@ -15,6 +12,9 @@ from xsoar_cli.utilities.config_file import (
     load_config,
 )
 
+if TYPE_CHECKING:
+    from xsoar_cli.xsoar_client.client import Client
+
 logger = logging.getLogger(__name__)
 
 
@@ -47,8 +47,9 @@ def get_config_file_template_contents() -> dict:
     }
 
 
-@click.group(help="Create, validate, and manage CLI configuration")
+@click.group()
 def config() -> None:
+    """Create, validate, and manage CLI configuration"""
     pass
 
 
@@ -67,8 +68,7 @@ def show(ctx: click.Context, masked: bool) -> None:
             if "azure_storage_access_token" in config["server_config"][key]:
                 config["server_config"][key]["azure_storage_access_token"] = "*****"  # noqa: S105
 
-    print(json.dumps(config, indent=4))
-    ctx.exit()
+    click.echo(json.dumps(config, indent=4))
 
 
 @click.command()
@@ -203,8 +203,28 @@ def set_azure_token(ctx: click.Context, environment: str, sastoken: str) -> None
     logger.info("Azure SAS token updated for environment '%s'", environment)
 
 
+@click.command()
+@click.option("--enable", "action", flag_value="enable", help="Enable the version update check on CLI startup.")
+@click.option("--disable", "action", flag_value="disable", help="Disable the version update check on CLI startup.")
+@click.pass_context
+@load_config
+def set_version_check(ctx: click.Context, action: str | None) -> None:  # noqa: ARG001
+    """Enable or disable the version update check on CLI startup."""
+    if action is None:
+        raise click.UsageError("Specify either --enable or --disable.")
+    config_file = get_config_file_path()
+    config_data = json.loads(config_file.read_text())
+    # skip_version_check is the inverse: enabling the check means skip=False.
+    config_data["skip_version_check"] = action == "disable"
+    config_file.write_text(json.dumps(config_data, indent=4))
+    state = "enabled" if action == "enable" else "disabled"
+    logger.info("Version check %s", state)
+    click.echo(f"Version check {state}.")
+
+
 config.add_command(create)
 config.add_command(validate)
 config.add_command(show)
 config.add_command(set_credentials)
 config.add_command(set_azure_token)
+config.add_command(set_version_check)

{xsoar_cli-2.1.1 → 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.1.1 → 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
 
@@ -19,7 +19,8 @@ logger = logging.getLogger(__name__)
 
 @click.group()
 def content() -> None:
-    """Inspect and manage content items."""
+    """Inspect and manage content items"""
+    pass
 
 
 @click.command()
@@ -27,21 +28,20 @@ def content() -> None:
 @click.option(
     "--type",
     "content_type",
-    type=click.Choice(["scripts", "playbooks", "all"], case_sensitive=False),
-    default="all",
-    show_default=True,
+    type=click.Choice(["scripts", "playbooks"], case_sensitive=False),
+    required=True,
     help="Type of content items to retrieve.",
 )
 @click.pass_context
 @load_config
-@validate_xsoar_connectivity()
+@validate_xsoar_connectivity
 def get_detached(ctx: click.Context, environment: str | None, content_type: str) -> None:
     """List detached content items."""
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
     response = xsoar_client.content.get_detached(content_type)
-    click.echo(json.dumps(response.json(), indent=4))
-    click.echo(f"Getting detached content items ({content_type=})")
+    data = json.loads(response)
+    click.echo(json.dumps(data, indent=4))
 
 
 # We name the command in the decorator here to avoid shadowing the builtin list.
@@ -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:
+@validate_xsoar_connectivity
+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))
 
 
@@ -98,7 +104,7 @@ def list_content(ctx: click.Context, environment: str | None, content_type: str,
 @click.argument("name", type=str)
 @click.pass_context
 @load_config
-@validate_xsoar_connectivity()
+@validate_xsoar_connectivity
 def download(ctx: click.Context, environment: str | None, content_type: str, output_path: str | None, name: str) -> None:
     """Download a content item by name.
 

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
+```