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

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

@@ -8,6 +8,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### 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.
+- `manifest update`, `manifest validate`, `manifest diff`, and `manifest deploy` now support file path tab completion for the manifest argument.
+
+## [2.1.0] - 2026-04-08
+
+### Added
+
+- `completions install` command to generate and install shell completion scripts for Bash, Zsh (including Oh My Zsh), and Fish. Auto-detects the current shell from `$SHELL`, overridable with `--shell`.
+- `completions uninstall` command to remove previously installed completion scripts.
+- Shell completion no longer triggers the version update check or logging setup, which previously leaked output into completion results.
+
+## [2.0.2] - 2026-04-08
+
+### Changed
+
 - Redesigned test suite into a two-layer structure: `tests/cli/` for CLI integration tests (CliRunner-based) and `tests/unit/` for direct unit tests. Replaced repetitive `@patch` decorator stacking and manual `CliRunner` instantiation with shared fixtures (`invoke`, `mock_xsoar_env`, `mock_content_env`, `mock_case_env`) and factory fixtures (`make_mock_client`, `make_http_error`, `make_case_response`).
 
 ### Removed
@@ -19,6 +34,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 
 - `content download` subcommand for downloading individual content items by name. Supports playbooks and layouts (`xsoar-cli content download --type playbook|layout <name>`).
+- `content download --output` option to specify the content repository root directory. Useful when running xsoar-cli from outside the content repository.
+- `content download` automatically runs `demisto-sdk format` on downloaded files to ensure they conform to the content repository standard.
+- `content download` re-attaches downloaded content items to their pack after writing, so they no longer appear as detached in XSOAR.
+- `content download` resolves the content item's pack ID and writes to the correct `Packs/<pack_id>/` directory. Prompts for fallback to the current working directory if the pack directory does not exist.
 
 ## [2.0.0] - 2026-04-07
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xsoar-cli
-Version: 2.0.2
+Version: 2.1.1
 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
@@ -111,6 +111,28 @@ Or with pip:
 pip uninstall xsoar-cli
 ```
 
+## Shell Completion
+
+xsoar-cli supports tab completion for Bash, Zsh, and Fish. Completion covers commands, subcommands, and options.
+
+The easiest way to set up completions is with the built-in command:
+
+```bash
+xsoar-cli completions install
+```
+
+This auto-detects your shell and writes the completion script to the appropriate location. Use `--shell` to specify a shell explicitly. For Zsh, Oh My Zsh is detected automatically.
+
+To remove completions:
+
+```bash
+xsoar-cli completions uninstall
+```
+
+Regenerate completions after upgrading xsoar-cli by running `xsoar-cli completions install` again.
+
+For manual setup or details, see the [completions command documentation](src/xsoar_cli/commands/completions/README.md).
+
 ## Configuration
 
 The xsoar-cli config file is located in `~/.config/xsoar-cli/config.json`. To create a configuration file from template, please run:
@@ -236,6 +258,7 @@ For more information on a specific command execute `xsoar-cli <command> --help`.
 ### Commands
 
 - **[case](src/xsoar_cli/commands/case/README.md)** - Retrieve case details and clone cases between environments
+- **[completions](src/xsoar_cli/commands/completions/README.md)** - Install and manage shell completion
 - **[content](src/xsoar_cli/commands/content/README.md)** - Inspect and manage content items on your XSOAR server
 - **[config](src/xsoar_cli/commands/config/README.md)** - Create, validate, and manage CLI configuration files
 - **[graph](src/xsoar_cli/commands/graph/README.md)** - Generate visual dependency graphs for content packs

{xsoar_cli-2.0.2 → xsoar_cli-2.1.1}/README.md

@@ -81,6 +81,28 @@ Or with pip:
 pip uninstall xsoar-cli
 ```
 
+## Shell Completion
+
+xsoar-cli supports tab completion for Bash, Zsh, and Fish. Completion covers commands, subcommands, and options.
+
+The easiest way to set up completions is with the built-in command:
+
+```bash
+xsoar-cli completions install
+```
+
+This auto-detects your shell and writes the completion script to the appropriate location. Use `--shell` to specify a shell explicitly. For Zsh, Oh My Zsh is detected automatically.
+
+To remove completions:
+
+```bash
+xsoar-cli completions uninstall
+```
+
+Regenerate completions after upgrading xsoar-cli by running `xsoar-cli completions install` again.
+
+For manual setup or details, see the [completions command documentation](src/xsoar_cli/commands/completions/README.md).
+
 ## Configuration
 
 The xsoar-cli config file is located in `~/.config/xsoar-cli/config.json`. To create a configuration file from template, please run:
@@ -206,6 +228,7 @@ For more information on a specific command execute `xsoar-cli <command> --help`.
 ### Commands
 
 - **[case](src/xsoar_cli/commands/case/README.md)** - Retrieve case details and clone cases between environments
+- **[completions](src/xsoar_cli/commands/completions/README.md)** - Install and manage shell completion
 - **[content](src/xsoar_cli/commands/content/README.md)** - Inspect and manage content items on your XSOAR server
 - **[config](src/xsoar_cli/commands/config/README.md)** - Create, validate, and manage CLI configuration files
 - **[graph](src/xsoar_cli/commands/graph/README.md)** - Generate visual dependency graphs for content packs

{xsoar_cli-2.0.2 → xsoar_cli-2.1.1}/_version.py

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

{xsoar_cli-2.0.2 → xsoar_cli-2.1.1}/src/xsoar_cli/cli.py

@@ -8,11 +8,13 @@
 
 import logging
 import logging.handlers
+import os
 import sys
 
 import click
 
 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.graph import commands as graph_commands
@@ -64,6 +66,7 @@ def cli(ctx: click.Context, debug: bool) -> None:
 
 def _register_commands() -> None:
     cli.add_command(case_commands.case)
+    cli.add_command(completions_commands.completions)
     cli.add_command(config_commands.config)
     cli.add_command(content_commands.content)
 
@@ -119,6 +122,13 @@ _setup: LoggingSetup | None = None
 def main() -> None:
     """Entry point (pyproject.toml console_scripts). Sets up logging, invokes
     the CLI, and ensures the exit code is logged before the process exits."""
+    # When Click is handling shell completion (Bash, Zsh, Fish) it re-invokes
+    # the CLI with _XSOAR_CLI_COMPLETE set. Skip logging and the version check
+    # so their output does not leak into the completion results.
+    if "_XSOAR_CLI_COMPLETE" in os.environ:
+        cli()
+        return
+
     # Start by setting up logging facilitites
     config_data = read_config_file()
     global _setup  # noqa: PLW0603

xsoar_cli-2.1.1/src/xsoar_cli/commands/completions/README.md

@@ -0,0 +1,47 @@
+# Completions
+
+Install and manage shell completion for xsoar-cli. Supports Bash, Zsh (including Oh My Zsh), and Fish.
+
+## Install
+
+Generate and install the shell completion script. The target shell is auto-detected from `$SHELL` if not specified.
+
+For Zsh, the install location is determined automatically:
+- **Oh My Zsh**: `$ZSH_CUSTOM/completions/_xsoar-cli`
+- **Plain Zsh**: `~/.zfunc/_xsoar-cli`
+
+**Syntax:** `xsoar-cli completions install [OPTIONS]`
+
+**Options:**
+- `--shell [bash|zsh|fish]` - Target shell. Auto-detected from `$SHELL` if not specified.
+
+**Examples:**
+```
+# Auto-detect shell
+xsoar-cli completions install
+
+# Specify shell explicitly
+xsoar-cli completions install --shell zsh
+xsoar-cli completions install --shell bash
+xsoar-cli completions install --shell fish
+```
+
+Regenerate completions after upgrading xsoar-cli by running the same command again.
+
+## Uninstall
+
+Remove a previously installed completion script. Uses the same detection logic as `install` to locate the file.
+
+**Syntax:** `xsoar-cli completions uninstall [OPTIONS]`
+
+**Options:**
+- `--shell [bash|zsh|fish]` - Target shell. Auto-detected from `$SHELL` if not specified.
+
+**Examples:**
+```
+# Auto-detect shell
+xsoar-cli completions uninstall
+
+# Specify shell explicitly
+xsoar-cli completions uninstall --shell zsh
+```

xsoar_cli-2.1.1/src/xsoar_cli/commands/completions/commands.py

@@ -0,0 +1,144 @@
+"""Shell completion install and uninstall commands."""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+
+import click
+
+logger = logging.getLogger(__name__)
+
+SHELLS = ("bash", "zsh", "fish")
+PROG_NAME = "xsoar-cli"
+COMPLETE_VAR = "_XSOAR_CLI_COMPLETE"
+
+
+def _detect_shell() -> str | None:
+    """Detect the current shell from the SHELL environment variable."""
+    shell_path = os.environ.get("SHELL", "")
+    if not shell_path:
+        return None
+    shell_name = Path(shell_path).name
+    if shell_name in SHELLS:
+        return shell_name
+    return None
+
+
+def _get_completion_path(shell: str) -> Path:
+    """Return the target path for the completion script."""
+    home = Path.home()
+    if shell == "zsh":
+        # Prefer Oh My Zsh custom completions directory if available.
+        zsh_custom = os.environ.get("ZSH_CUSTOM")
+        if zsh_custom:
+            return Path(zsh_custom) / "completions" / f"_{PROG_NAME}"
+        omz_default = home / ".oh-my-zsh"
+        if omz_default.is_dir():
+            return omz_default / "custom" / "completions" / f"_{PROG_NAME}"
+        return home / ".zfunc" / f"_{PROG_NAME}"
+    if shell == "bash":
+        return home / f".{PROG_NAME}-complete.bash"
+    if shell == "fish":
+        return home / ".config" / "fish" / "completions" / f"{PROG_NAME}.fish"
+    msg = f"Unsupported shell: {shell}"
+    raise ValueError(msg)
+
+
+def _generate_completion_script(shell: str) -> str:
+    """Generate the Click completion script for the given shell."""
+    # Lazy import to avoid circular import at module load time. The cli
+    # module imports this command group at startup, but this function is
+    # only called when the user runs "completions install".
+    from click.shell_completion import get_completion_class  # Lazy import for performance reasons
+
+    from xsoar_cli.cli import cli as cli_group  # Lazy import for performance reasons
+
+    cls = get_completion_class(shell)
+    if cls is None:
+        msg = f"No completion support for shell: {shell}"
+        raise click.ClickException(msg)
+    comp = cls(cli_group, {}, PROG_NAME, COMPLETE_VAR)
+    return comp.source()
+
+
+def _resolve_shell(shell_name: str | None) -> str:
+    """Return a validated shell name, auto-detecting if not provided."""
+    if shell_name is not None:
+        return shell_name
+    detected = _detect_shell()
+    if detected is None:
+        raise click.ClickException("Could not detect shell from $SHELL. Use --shell to specify it explicitly.")
+    return detected
+
+
+@click.group(help="Install and manage shell completion for xsoar-cli.")
+def completions() -> None:
+    pass
+
+
+@click.command()
+@click.option(
+    "--shell",
+    "shell_name",
+    type=click.Choice(SHELLS),
+    default=None,
+    help="Target shell. Auto-detected from $SHELL if not specified.",
+)
+def install(shell_name: str | None) -> None:
+    """Install shell completion for xsoar-cli."""
+    shell = _resolve_shell(shell_name)
+    script = _generate_completion_script(shell)
+    target = _get_completion_path(shell)
+
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(script)
+    logger.info("Wrote %s completion script to %s", shell, target)
+    click.echo(f"Completion script written to {target}")
+
+    if shell == "zsh":
+        zsh_custom = os.environ.get("ZSH_CUSTOM")
+        omz_dir = Path.home() / ".oh-my-zsh"
+        if not zsh_custom and not omz_dir.is_dir():
+            click.echo(
+                "\nAdd the following to your ~/.zshrc (before compinit):"
+                "\n\n  fpath+=~/.zfunc"
+                "\n  autoload -Uz compinit && compinit"
+                "\n\nThen reload with: exec zsh"
+            )
+        else:
+            click.echo("\nReload your shell with: exec zsh")
+    elif shell == "bash":
+        click.echo(f"\nAdd the following to your ~/.bashrc:\n\n  source {target}\n\nThen reload with: source ~/.bashrc")
+    elif shell == "fish":
+        click.echo("\nNo further configuration needed. Reload with: exec fish")
+
+
+@click.command()
+@click.option(
+    "--shell",
+    "shell_name",
+    type=click.Choice(SHELLS),
+    default=None,
+    help="Target shell. Auto-detected from $SHELL if not specified.",
+)
+def uninstall(shell_name: str | None) -> None:
+    """Remove shell completion for xsoar-cli."""
+    shell = _resolve_shell(shell_name)
+    target = _get_completion_path(shell)
+
+    if not target.is_file():
+        click.echo(f"No completion file found at {target}")
+        return
+
+    target.unlink()
+    logger.info("Removed %s completion script from %s", shell, target)
+    click.echo(f"Removed completion file {target}")
+
+    if shell == "bash":
+        click.echo(f"\nRemember to remove the following line from your ~/.bashrc:\n\n  source {target}")
+
+
+completions.add_command(install)
+completions.add_command(uninstall)

{xsoar_cli-2.0.2 → xsoar_cli-2.1.1}/src/xsoar_cli/commands/manifest/README.md

@@ -4,20 +4,19 @@ Content pack deployment management commands using a declarative configuration fi
 
 ## Generate
 
-Generate a new manifest file from currently installed content packs. Assumes all packs are marketplace packs (no custom packs).
+Generate a new manifest file from currently installed content packs. Assumes all packs are marketplace packs (no custom packs). The output file is always named `xsoar_config.json`. Prompts for confirmation if the file already exists.
 
-**Syntax:** `xsoar-cli manifest generate [OPTIONS] MANIFEST_PATH`
+**Syntax:** `xsoar-cli manifest generate [OPTIONS]`
 
 **Options:**
 - `--environment TEXT` - Target environment (default: uses default environment from config)
-
-**Arguments:**
-- `MANIFEST_PATH` - Path where the new manifest file will be created
+- `--output-dir DIRECTORY` - Directory to write xsoar_config.json to (default: current directory)
 
 **Examples:**
 ```
-xsoar-cli manifest generate ./xsoar_config.json
-xsoar-cli manifest generate --environment prod ./xsoar_config.json
+xsoar-cli manifest generate
+xsoar-cli manifest generate --output-dir /path/to/repo
+xsoar-cli manifest generate --environment prod
 ```
 
 ## Validate

{xsoar_cli-2.0.2 → xsoar_cli-2.1.1}/src/xsoar_cli/commands/manifest/commands.py

@@ -118,18 +118,31 @@ def manifest() -> None:
     """Various commands to interact/update/deploy content packs defined in the xsoar_config.json manifest."""
 
 
+MANIFEST_FILENAME = "xsoar_config.json"
+
+
 @click.command()
 @click.option("--environment", default=None, help="Default environment set in config file.")
-@click.argument("manifest_path", type=str)
+@click.option(
+    "--output-dir",
+    type=click.Path(exists=True, file_okay=False),
+    default=".",
+    show_default=True,
+    help="Directory to write xsoar_config.json to.",
+)
 @click.pass_context
 @load_config
 @validate_xsoar_connectivity()
-def generate(ctx: click.Context, environment: str | None, manifest_path: str) -> None:
+def generate(ctx: click.Context, environment: str | None, output_dir: str) -> None:
     """Generate a new xsoar_config.json manifest from installed content packs.
 
     This command assumes that you do not have any custom content packs uploaded to XSOAR.
     All packs will be added as "marketplace_packs" in the manifest.
     """
+    manifest_path = str(Path(output_dir) / MANIFEST_FILENAME)
+    if Path(manifest_path).is_file():
+        click.confirm(f"{manifest_path} already exists. Overwrite?", abort=True)
+
     config = get_xsoar_config(ctx)
     xsoar_client: Client = config.get_client(environment)
     logger.info("Generating manifest from installed packs (environment: '%s')", environment or config.default_environment)
@@ -151,7 +164,7 @@ def generate(ctx: click.Context, environment: str | None, manifest_path: str) ->
 
 @click.command()
 @click.option("--environment", default=None, help="Default environment set in config file.")
-@click.argument("manifest", type=str)
+@click.argument("manifest", type=click.Path(exists=True))
 @click.pass_context
 @load_config
 @validate_artifacts_provider
@@ -239,7 +252,7 @@ def update(ctx: click.Context, environment: str | None, manifest: str) -> None:
     default="diff",
     help="Validate the full manifest, or only the definitions that diff with installed versions",
 )
-@click.argument("manifest", type=str)
+@click.argument("manifest", type=click.Path(exists=True))
 @click.pass_context
 @load_config
 @validate_artifacts_provider
@@ -304,7 +317,7 @@ def validate(ctx: click.Context, environment: str | None, mode: str, manifest: s
 
 @click.command()
 @click.option("--environment", default=None, help="Default environment set in config file.")
-@click.argument("manifest", type=str)
+@click.argument("manifest", type=click.Path(exists=True))
 @click.pass_context
 @load_config
 @validate_xsoar_connectivity()
@@ -362,7 +375,7 @@ def diff(ctx: click.Context, manifest: str, environment: str | None) -> None:
 @click.option("--environment", default=None, help="Default environment set in config file.")
 @click.option("--verbose", is_flag=True, default=False)
 @click.option("--yes", is_flag=True, default=False)
-@click.argument("manifest", type=str)
+@click.argument("manifest", type=click.Path(exists=True))
 @click.pass_context
 @load_config
 @validate_artifacts_provider