xsoar-cli 0.0.3__py3-none-any.whl

xsoar_cli/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Torbjørn Lium <torben@lium.org>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.3"

xsoar_cli/__init__.py

@@ -0,0 +1 @@
+

xsoar_cli/case/README.md

@@ -0,0 +1,31 @@
+# Case
+
+**Various case/incident related commands**
+
+## Clone
+It may be useful to clone a case from the production environment to the dev environment. This will of course require a configuration file
+with API keys for both environments. The syntax is `xsoar-cli case clone --dest TEXT --source TEXT CASENUMBER` where default environments for `dest` and `source` are "dev" and "prod", respectively.
+
+#### Example invocation
+```
+xsoar-cli case clone --dest prod --source dev 312412  # explicitly using the default options
+xsoar-cli case clone 312412                           # shorthand for the same invocation as above
+```
+
+
+## Create
+It may be useful to create a case in the dev environment. The syntax is `xsoar-cli case create [OPTIONS] [NAME] [DETAILS]` where NAME and
+DETAILS are optional. If NAME and DETAILS are not filled in, then default values are used.
+#### Example invocation
+```
+xsoar-cli case create 312412
+xsoar-cli case create 312412 "This is the name/title of the case" "This is some descriptive text on what the case is about."
+```
+
+
+## Get
+It may be useful to quickly fetch some case data. The syntax is `xsoar-cli case clone [OPTIONS] CASENUMBER` and the command outputs raw JSON indented with 4 whitespaces to make the resulting output at least somewhat readable.
+#### Example invocation
+```
+xsoar-cli case get 312412
+```

xsoar_cli/case/commands.py

@@ -0,0 +1,86 @@
+import json
+from typing import TYPE_CHECKING
+
+import click
+
+from xsoar_cli.utilities import load_config, validate_environments
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+@click.group(help="Add new or modify existing XSOAR case")
+def case() -> None:
+    pass
+
+
+@click.argument("casenumber", type=int)
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.command(help="Get basic information about a single case in XSOAR")
+@click.pass_context
+@load_config
+def get(ctx: click.Context, casenumber: int, environment: str) -> None:
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    response = xsoar_client.get_case(casenumber)
+    if response["total"] == 0 and not response["data"]:
+        click.echo(f"Cannot find case ID {casenumber}")
+        ctx.exit(1)
+    click.echo(json.dumps(response, indent=4))
+
+
+@click.argument("casenumber", type=int)
+@click.option("--source", default="prod", show_default=True, help="Source environment")
+@click.option("--dest", default="dev", show_default=True, help="Destination environment")
+@click.command()
+@click.pass_context
+@load_config
+def clone(ctx: click.Context, casenumber: int, source: str, dest: str) -> None:
+    """Clones a case from source to destination environment."""
+    valid_envs = validate_environments(source, dest, ctx=ctx)
+    if not valid_envs:
+        click.echo(f"Error: cannot find environments {source} and/or {dest} in config")
+        ctx.exit(1)
+    xsoar_source_client: Client = ctx.obj["server_envs"][source]
+    results = xsoar_source_client.get_case(casenumber)
+    data = results["data"][0]
+    # Dbot mirror info is irrelevant. This will be added again if applicable by XSOAR after ticket creation in dev.
+    data.pop("dbotMirrorId")
+    data.pop("dbotMirrorInstance")
+    data.pop("dbotMirrorDirection")
+    data.pop("dbotDirtyFields")
+    data.pop("dbotCurrentDirtyFields")
+    data.pop("dbotMirrorTags")
+    data.pop("dbotMirrorLastSync")
+    data.pop("id")
+    data.pop("created")
+    data.pop("modified")
+    # Ensure that playbooks run immediately when the case is created
+    data["createInvestigation"] = True
+
+    xsoar_dest_client: Client = ctx.obj["server_envs"][dest]
+    case_data = xsoar_dest_client.create_case(data=data)
+    click.echo(json.dumps(case_data, indent=4))
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.argument("details", type=str, default="Placeholder case details")
+@click.argument("name", type=str, default="Test case created from xsoar-cli")
+@click.command(help="Creates a single new case in XSOAR")
+@click.pass_context
+@load_config
+def create(ctx: click.Context, environment: str, name: str, details: str) -> None:
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    data = {
+        "createInvestigation": True,
+        "name": name,
+        "type": "MyCaseType",  # grab this from config maybe?
+        "details": details,
+    }
+    case_data = xsoar_client.create_case(data=data)
+    case_id = case_data["id"]
+    click.echo(f"Created XSOAR case {case_id}")
+
+
+case.add_command(get)
+case.add_command(clone)
+case.add_command(create)

xsoar_cli/cli.py

@@ -0,0 +1,41 @@
+import logging
+
+import click
+
+from .__about__ import __version__
+from .case import commands as case_commands
+from .config import commands as config_commands
+from .graph import commands as graph_commands
+from .manifest import commands as manifest_commands
+from .pack import commands as pack_commands
+from .playbook import commands as playbook_commands
+from .plugins import commands as plugin_commands
+from .plugins.manager import PluginManager
+
+
+@click.group()
+@click.pass_context
+@click.version_option(__version__)
+@click.option("--debug", is_flag=True, help="Enable debug logging")
+def cli(ctx: click.Context, debug: bool) -> None:
+    """XSOAR CLI - Command line interface for XSOAR operations."""
+    if debug:
+        logging.basicConfig(level=logging.DEBUG)
+
+
+cli.add_command(config_commands.config)
+cli.add_command(case_commands.case)
+cli.add_command(pack_commands.pack)
+cli.add_command(manifest_commands.manifest)
+cli.add_command(playbook_commands.playbook)
+cli.add_command(graph_commands.graph)
+cli.add_command(plugin_commands.plugins)
+
+# Load and register plugins after all core commands are added
+plugin_manager = PluginManager()
+try:
+    plugin_manager.load_all_plugins(ignore_errors=True)
+    plugin_manager.register_plugin_commands(cli)
+except Exception:
+    # Silently ignore plugin loading errors to not break the CLI
+    pass

xsoar_cli/config/README.md

@@ -0,0 +1,12 @@
+# Config
+At the moment, only a single config command is implemented
+
+## Create
+Creates a new configuration file in `~/.config/xsoar-cli/config.json` based on a template. If the file already exists, then the user is prompted to overwrite
+the existing file.
+
+## Get
+Reads the current configuration file and prints it out as JSON indented with 4 whitespaces. API keys are masked from output.
+
+## Validate
+Ensures that the configuration file is valid parsable JSON and that each server environment defined is reachable.

xsoar_cli/config/commands.py

@@ -0,0 +1,99 @@
+import json
+from typing import TYPE_CHECKING
+
+import click
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+import contextlib
+
+from xsoar_cli.utilities import get_config_file_contents, get_config_file_path, get_config_file_template_contents, load_config
+
+
+@click.group(help="Create/validate etc")
+def config() -> None:
+    pass
+
+
+@click.command()
+@click.option("--unmask", "masked", is_flag=True, default=False)
+@click.pass_context
+@load_config
+def show(ctx: click.Context, masked: bool) -> None:
+    """Prints out current config. API keys are masked."""
+    config_file = get_config_file_path()
+    config = get_config_file_contents(config_file)
+    if not masked:
+        for key in config["server_config"]:
+            config["server_config"][key]["api_token"] = "MASKED"  # noqa: S105
+    print(json.dumps(config, indent=4))
+    ctx.exit()
+
+
+@click.command()
+@click.option("--only-test-environment", default=None, show_default=True, help="Environment as defined in config file")
+@click.pass_context
+@load_config
+def validate(ctx: click.Context, only_test_environment: str) -> None:
+    """Validates that the configuration file is JSON and tests connectivity for each XSOAR Client environment defined."""
+    return_code = 0
+    for server_env in ctx.obj["server_envs"]:
+        if only_test_environment and server_env != only_test_environment:
+            # Ignore environment if --only-test-environment option is given and environment does not match
+            # what the user specified in option
+            continue
+        click.echo(f'Testing "{server_env}" environment...', nl=False)
+        xsoar_client: Client = ctx.obj["server_envs"][server_env]
+        try:
+            xsoar_client.test_connectivity()
+        except ConnectionError as ex:
+            raise RuntimeError from ex
+            click.echo("FAILED")
+            return_code = 1
+            continue
+        click.echo("OK")
+    ctx.exit(return_code)
+
+
+@click.command()
+def create() -> None:
+    """Create a new configuration file based on a template."""
+    # if confdir does not exist, create it
+    # if conf file does not exist, create it
+    config_file = get_config_file_path()
+    if config_file.is_file():
+        click.confirm(f"WARNING: {config_file} already exists. Overwrite?", abort=True)
+    config_file.parent.mkdir(exist_ok=True, parents=True)
+    config_data = get_config_file_template_contents()
+    config_file.write_text(json.dumps(config_data, indent=4))
+    click.echo(f"Wrote template configuration file {config_file}")
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.option("--key_id", type=int, help="If set then server config for server_version will be set to 8.")
+@click.argument("apitoken", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def set_credentials(ctx: click.Context, environment: str, apitoken: str, key_id: int) -> None:  # noqa: ARG001
+    """Set individual credentials for an environment in the config file."""
+    config_file = get_config_file_path()
+    config_data = json.loads(config_file.read_text())
+    config_data["server_config"][environment]["api_token"] = apitoken
+    # If we are given an API key ID, then we know it's supposed to be used in XSOAR 8.
+    # Set or remove the xsiam_auth_id accordingly.
+    if key_id:
+        config_data["server_config"][environment]["xsiam_auth_id"] = key_id
+        config_data["server_config"][environment]["server_version"] = 8
+    else:
+        config_data["server_config"][environment]["server_version"] = 6
+        with contextlib.suppress(KeyError):
+            config_data["server_config"][environment].pop("xsiam_auth_id")
+    config_file.write_text(json.dumps(config_data, indent=4))
+
+
+config.add_command(create)
+config.add_command(validate)
+config.add_command(show)
+config.add_command(set_credentials)

xsoar_cli/graph/README.md

@@ -0,0 +1,17 @@
+# Graph
+BETA command. Under active development.
+
+## Generate
+Creates a graph representation of the entire content repository and plots connected components. The syntax is `xsoar-cli graph generate [OPTIONS] [PACKS]...`
+where the only required option is the path to the content repository. An optional PACKS argument can be specified with the paths of one or more content packs
+you want to be plotted.
+
+### Example invocations
+```
+# Plot the connected components from the graph of the entire content repository
+xsoar-cli graph generate -rp ./content_repo
+# Plot only the components found in MyFirstPack
+xsoar-cli graph generate -rp ./content_repo ./content_repo/Packs/MyFirstPack
+# Plot only connected components from MyFirstPack and MySecondPack
+xsoar-cli graph generate -rp ./content_repo ./content_repo/Packs/MyFirstPack ./content_repo/Packs/MySecondPack
+```

xsoar_cli/graph/commands.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import click
+from xsoar_dependency_graph.xsoar_dependency_graph import ContentGraph
+
+
+@click.group(help="(BETA) Create dependency graphs from one or more content packs")
+def graph() -> None:
+    pass
+
+
+@click.option("-rp", "--repo-path", required=True, type=click.Path(exists=True), help="Path to content repository")
+@click.argument("packs", nargs=-1, required=False, type=click.Path(exists=True))
+@click.command()
+def generate(packs: tuple[Path], repo_path: Path) -> None:
+    """BETA
+
+    Generates a XSOAR dependency graph for one or more content packs. If no packs are defined in the [PACKS] argument,
+    a dependency graph is created for all content packs in the content repository.
+
+    Usage examples:
+
+    xsoar-cli graph generate -rp . Packs/Pack_one Packs/Pack_two
+
+    xsoar-cli graph generate -rp ."""
+    cg: ContentGraph = ContentGraph(repo_path=Path(repo_path))
+    packs_list = [Path(item) for item in packs]
+    cg.create_content_graph(pack_paths=packs_list)
+    cg.plot_connected_components()
+
+
+graph.add_command(generate)

xsoar_cli/manifest/README.md

@@ -0,0 +1,23 @@
+# Manifest
+
+## Validate
+Verifies that the xsoar_config.json manifest is valid JSON. Does a HTTP HEAD calls to every upstream content pack defined. Checks
+custom content pack availability in AWS S3 artefact repository.
+```
+xsoar-cli manifest validate /my/full/path/to/xsoar_config.json
+xsoar-cli manifest validate relative/path/to/xsoar_config.json
+```
+
+## Update
+Updates and prompts the user to write the xsoar_config.json manifest with the latest available content packs. Both upstream and custom content packs are checked.
+```
+xsoar-cli manifest update /my/full/path/to/xsoar_config.json
+xsoar-cli manifest update relative/path/to/xsoar_config.json
+```
+
+## Diff
+Queries the XSOAR server for installed packages and compares them to what is defined in the manifest. Prints out the diff.
+```
+xsoar-cli manifest diff /my/full/path/to/xsoar_config.json
+xsoar-cli manifest diff relative/path/to/xsoar_config.json
+```

xsoar_cli/manifest/commands.py

@@ -0,0 +1,200 @@
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from xsoar_cli.utilities import load_config
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+def load_manifest(manifest: str):  # noqa: ANN201
+    """Calls json.load() on the manifest and returns a dict."""
+    filepath = Path(manifest)
+    try:
+        return json.load(filepath.open("r"))
+    except json.JSONDecodeError:
+        msg = f"Failed to decode JSON in {filepath}"
+        click.echo(msg)
+        sys.exit(1)
+    except FileNotFoundError:
+        print(f"File not found: {filepath}")
+        sys.exit(1)
+
+
+def write_manifest(manifest: str, data: Any) -> None:  # noqa: ANN401
+    """Writes the xsoar_conf.json manifest using json.dumps()"""
+    manifest_path = Path(manifest)
+    with manifest_path.open("w") as f:
+        f.write(json.dumps(data, indent=4))
+        f.write("\n")
+    click.echo(f"Written updated manifest to '{manifest_path}'")
+
+
+@click.group()
+def manifest() -> None:
+    """Various commands to interact/update/deploy content packs defined in the xsoar_config.json manifest."""
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def update(ctx: click.Context, environment: str, manifest: str) -> None:
+    """Update manifest on disk with latest available content pack versions."""
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    manifest_data = load_manifest(manifest)
+    click.echo("Fetching outdated packs from XSOAR server. This may take a minute...", nl=False)
+    results = xsoar_client.get_outdated_packs()
+    click.echo("done.")
+    if not results:
+        click.echo("No packs eligible for upgrade.")
+        sys.exit(0)
+
+    item1 = "Pack ID"
+    item2 = "Installed version"
+    item3 = "Latest available version"
+    header = f"{item1:50}{item2:20}{item3:20}"
+    click.echo(header)
+    for pack in results:
+        click.echo(f"{pack['id']:50}{pack['currentVersion']:20}{pack['latest']:20}")
+    click.echo(f"Total number of outdated content packs: {len(results)}")
+
+    for pack in results:
+        key = "custom_packs" if pack["author"] in ctx.obj["custom_pack_authors"] else "marketplace_packs"
+        index = next((i for i, item in enumerate(manifest_data[key]) if item["id"] == pack["id"]), None)
+        if index is None:
+            msg = f"Pack {pack['id']} not found in manifest."
+            click.echo(msg)
+            sys.exit(1)
+        comment = manifest_data[key][index].get("_comment", None)
+        if comment is not None:
+            print(f"WARNING: comment found in manifest for {pack['id']}: {comment}")
+        msg = f"Upgrade {pack['id']} from {pack['currentVersion']} to {pack['latest']}?"
+        should_upgrade = click.confirm(msg, default=True)
+        if should_upgrade:
+            manifest_data[key][index]["version"] = pack["latest"]
+    write_manifest(manifest, manifest_data)
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def validate(ctx: click.Context, environment: str, manifest: str) -> None:
+    """Validate manifest JSON and all pack availability. Validates upstream pack availability by doing HTTP CONNECT.
+    Custom pack availability is implementation dependant."""
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    manifest_data = load_manifest(manifest)
+    click.echo("Manifest is valid JSON")
+    keys = ["custom_packs", "marketplace_packs"]
+    for key in keys:
+        custom = key == "custom_packs"
+        click.echo(f"Checking {key} availability ", nl=False)
+        for pack in manifest_data[key]:
+            if not xsoar_client.is_pack_available(pack_id=pack["id"], version=pack["version"], custom=custom):
+                # If we are in a merge request and the merge request contains a new pack as well
+                # as a updated xsoar_config.json manifest, then the pack is not available in S3
+                # before the MR is merged. Check if we can find the appropriate pack version locally
+                # If so, we can ignore this error because the pack will become available after merge.
+                manifest_arg = Path(manifest)
+                manifest_path = manifest_arg.resolve()
+                repo_path = manifest_path.parent
+                pack_metadata_path = Path(f"{repo_path}/Packs/{pack['id']}/pack_metadata.json")
+                with Path.open(pack_metadata_path, encoding="utf-8") as f:
+                    pack_metadata = json.load(f)
+
+                if pack_metadata["currentVersion"] == pack["version"]:
+                    continue
+                # The object key does not exist in AWS S3, and the relevant Pack locally does not have
+                # the requested version.
+                click.echo(f"\nFailed to reach pack {pack['id']} version {pack['version']}")
+                sys.exit(1)
+            click.echo(".", nl=False)
+        print()
+
+    click.echo("Manifest is valid JSON and all packs are reachable.")
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.argument("manifest", type=str)
+@click.command()
+@click.pass_context
+@load_config
+def diff(ctx: click.Context, manifest: str, environment: str) -> None:
+    """Prints out the differences (if any) between what is defined in the xsoar_config.json manifest and what is actually
+    installed on the XSOAR server."""
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    manifest_data = load_manifest(manifest)
+    installed_packs = xsoar_client.get_installed_packs()
+    all_good = True
+    for key in manifest_data:
+        for pack in manifest_data[key]:
+            installed = next((item for item in installed_packs if item["id"] == pack["id"]), {})
+            if not installed:
+                click.echo(f"Pack {pack['id']} is not installed")
+                all_good = False
+            elif installed["currentVersion"] != pack["version"]:
+                msg = f"Manifest states {pack['id']} version {pack['version']} but version {installed['currentVersion']} is installed"
+                click.echo(msg)
+                all_good = False
+    if all_good:
+        click.echo("All packs up to date.")
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.option("--verbose", is_flag=True, default=False)
+@click.option("--yes", is_flag=True, default=False)
+@click.command()
+@click.argument("manifest", type=str)
+@click.pass_context
+@load_config
+def deploy(ctx: click.Context, environment: str, manifest: str, verbose: bool, yes: bool) -> None:  # noqa: FBT001
+    """
+    Deploys content packs to the XSOAR server as defined in the xsoar_config.json manifest.
+    The PATH argument expects the full or relative path to xsoar_config.json
+
+    \b
+    Prompts for confirmation prior to pack installation.
+    """
+    should_continue = True
+    if not yes:
+        should_continue = click.confirm(
+            f"WARNING: this operation will attempt to deploy all packs defined in the manifest to XSOAR {environment} environment. Continue?",
+        )
+    if not should_continue:
+        ctx.exit()
+
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    manifest_data = load_manifest(manifest)
+    click.echo("Fetching installed packs...", err=True)
+    installed_packs = xsoar_client.get_installed_packs()
+    click.echo("done.")
+    none_installed = True
+    for key in manifest_data:
+        custom = key == "custom_packs"
+        for pack in manifest_data[key]:
+            installed = next((item for item in installed_packs if item["id"] == pack["id"]), {})
+            if not installed or installed["currentVersion"] != pack["version"]:
+                # Install pack
+                click.echo(f"Installing {pack['id']} version {pack['version']}...", nl=False)
+                xsoar_client.deploy_pack(pack_id=pack["id"], pack_version=pack["version"], custom=custom)
+                click.echo("OK.")
+                none_installed = False
+            elif verbose:
+                click.echo(f"Not installing {pack['id']} version {pack['version']}. Already installed.")
+                # Print message that install is skipped
+
+    if none_installed:
+        click.echo("No packs to install. XSOAR server is up to date with manifest.")
+
+
+manifest.add_command(deploy)
+manifest.add_command(diff)
+manifest.add_command(update)
+manifest.add_command(validate)

xsoar_cli/pack/README.md

@@ -0,0 +1,7 @@
+# Pack
+
+## Delete
+
+## Deploy
+
+## Get outdated

xsoar_cli/pack/commands.py

@@ -0,0 +1,55 @@
+import sys
+from typing import TYPE_CHECKING
+
+import click
+
+from xsoar_cli.utilities import load_config
+
+if TYPE_CHECKING:
+    from xsoar_client.xsoar_client import Client
+
+
+@click.group()
+@click.pass_context
+def pack(ctx: click.Context) -> None:
+    """Various content pack related commands."""
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.command()
+@click.argument("pack_id", type=str)
+@click.pass_context
+@load_config
+def delete(ctx: click.Context, environment: str, pack_id: str) -> None:
+    """Deletes a content pack from the XSOAR server."""
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    if not xsoar_client.is_installed(pack_id=pack_id):
+        click.echo(f"Pack ID {pack_id} is not installed. Cannot delete.")
+        sys.exit(1)
+    xsoar_client.delete(pack_id=pack_id)
+    click.echo(f"Deleted pack {pack_id} from XSOAR {environment}")
+
+
+@click.option("--environment", default="dev", show_default=True, help="Environment as defined in config file")
+@click.command()
+@click.pass_context
+@load_config
+def get_outdated(ctx: click.Context, environment: str) -> None:
+    """Prints out a list of outdated content packs."""
+    xsoar_client: Client = ctx.obj["server_envs"][environment]
+    click.echo("Fetching outdated packs. This may take a little while...", err=True)
+    outdated_packs = xsoar_client.get_outdated_packs()
+    if not outdated_packs:
+        click.echo("No outdated packs found")
+        sys.exit(0)
+    id_header = "Pack ID"
+    installed_header = "Installed version"
+    latest_header = "Latest version"
+    click.echo(f"{id_header:<50}{installed_header:>17}{latest_header:>17}")
+    for pack in outdated_packs:
+        msg = f"{pack['id']:<50}{pack['currentVersion']:>17}{pack['latest']:>17}"
+        click.echo(msg)
+
+
+pack.add_command(delete)
+pack.add_command(get_outdated)

xsoar_cli/playbook/README.md

@@ -0,0 +1,19 @@
+# Playbook
+
+## Download
+**This command requires a content repository-like directory structure in the current working directory**
+It attempts to provide a smoother development experience when modifying playbooks by doing the following steps:
+1. download the playbook. Attempts to detect the proper content pack and outputs the file to $(cwd)/Packs/PackID/Playbooks/<playbook name>.yml
+2. run demisto-sdk format --assume-yes --no-validate --no-graph <playbook_name.yml>
+3. re-attach the downloaded playbook in XSOAR
+Whitespace characters in Pack ID and Playbook name will be converted to underscores "_".
+
+### Current limitations
+- This command only supports downloading playbooks which are already part of a content pack. Proper implementation on completely new
+playbooks is yet to be implemented.
+- Attempting to download a non-existing playbook will result in a 500 Internal Server Error
+
+#### Example invocation:
+```
+xsoar-cli playbook download "my awesome playbook.yml"
+```