cli: add shell completion scripts (--print-completion)

generate bash/zsh/tcsh/fish/powershell completion scripts from the
argparse parser via shtab, so completions always match the CLI args

- floss --print-completion {bash,zsh,...} emits an installable script
- the sample positional completes file paths
- choice values (--string-type, --format, --language, --columns)
  complete automatically from argparse definitions
- document per-shell installation in doc/usage.md

fixes #1350

doc/usage.md

@@ -275,6 +275,35 @@ After this option is installed, you can right-click on any file and select `Open
  to quickly open the target file with FLOSS for analysis.
 
 
+### Shell completions (`--print-completion {bash,zsh,tcsh,fish,powershell}`)
+
+FLOSS can print a tab-completion script for your shell. The script is generated
+from FLOSS's argument definitions, so flags, choice values (such as
+`--string-type static`), and sample file paths all complete as you type.
+
+    floss --print-completion bash
+
+Install the output for your shell:
+
+bash:
+
+    mkdir -p ~/.local/share/bash_completion
+    floss --print-completion bash > ~/.local/share/bash_completion/floss
+    echo 'source ~/.local/share/bash_completion/floss' >> ~/.bashrc
+
+zsh (requires `compinit`, which most frameworks and default configs run):
+
+    mkdir -p ~/.local/share/zsh/site-functions
+    floss --print-completion zsh > ~/.local/share/zsh/site-functions/_floss
+
+fish:
+
+    mkdir -p ~/.config/fish/completions
+    floss --print-completion fish > ~/.config/fish/completions/floss.fish
+
+Then restart your shell or start a new one.
+
+
 ## <a name="shellcode"></a>Shellcode analysis options
 
 Malicious shellcode often times contains obfuscated strings or stackstrings.

floss/cli.py

@@ -24,6 +24,8 @@ from enum import Enum
 from typing import List, Optional
 from pathlib import Path
 
+import shtab
+
 import floss.utils
 import floss.logging_
 from floss.const import (
@@ -151,6 +153,7 @@ def make_parser():
         """)
 
     parser = ArgumentParser(
+        prog="floss",
         description=desc,
         epilog=epilog,
         formatter_class=argparse.RawDescriptionHelpFormatter,
@@ -164,11 +167,13 @@ def make_parser():
         help="minimum string length",
     )
 
-    parser.add_argument(
+    sample_argument = parser.add_argument(
         "sample",
         type=argparse.FileType("rb"),
         help="path to sample to analyze",
     )
+    # enable file path completion for the sample positional argument
+    setattr(sample_argument, "complete", shtab.FILE)
 
     analysis_group = parser.add_argument_group("analysis arguments")
     analysis_group.add_argument(
@@ -335,6 +340,12 @@ def make_parser():
             help="uninstall FLOSS from the right-click context menu for Windows Explorer and exit",
         )
 
+    shtab.add_argument_to(
+        parser,
+        ["--print-completion"],
+        help="print shell completion script for the given shell",
+    )
+
     output_group = parser.add_argument_group("rendering arguments")
     output_group.add_argument("-j", "--json", action="store_true", help="emit JSON instead of text")
     output_group.add_argument(

pyproject.toml

@@ -82,6 +82,7 @@ dependencies = [
     "tqdm>=4",
     "halo>=0.0.31",
     "rich>=13",
+    "shtab>=1.7",
     "pefile>=2022.5.30",
     "binary2strings>=0.1",
 

requirements.txt

@@ -52,6 +52,7 @@ python-lancelot==0.10.0
 pyyaml==6.0.1
 rich==15.0.0
 setuptools==84.0.0
+shtab==1.12.0
 six==1.17.0
 sortedcontainers==2.4.0
 spinners==0.0.24

tests/test_completion.py

@@ -0,0 +1,68 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+import pytest
+
+import floss.main
+
+
+@pytest.mark.parametrize("shell", ["bash", "zsh", "fish"])
+def test_print_completion(shell, capsys):
+    """--print-completion emits a non-empty completion script and exits cleanly."""
+    with pytest.raises(SystemExit) as excinfo:
+        floss.main.main(["--print-completion", shell])
+    assert excinfo.value.code == 0
+
+    out = capsys.readouterr().out
+    assert out.strip()
+    # all generated scripts reference the program by name
+    assert "floss" in out
+
+
+def test_print_completion_bash(capsys):
+    """the bash script completes flags, choices, and the sample file path."""
+    with pytest.raises(SystemExit):
+        floss.main.main(["--print-completion", "bash"])
+
+    out = capsys.readouterr().out
+    assert "--string-type" in out
+    # choice values from argparse are embedded
+    assert "static stack tight decoded language all" in out
+    # the sample positional completes file paths
+    assert "_shtab_compgen_files" in out
+
+
+def test_print_completion_zsh(capsys):
+    """the zsh script uses the #compdef header so compinit registers it."""
+    with pytest.raises(SystemExit):
+        floss.main.main(["--print-completion", "zsh"])
+
+    out = capsys.readouterr().out
+    assert out.startswith("#compdef floss")
+
+
+def test_print_completion_fish(capsys):
+    """the fish script registers completions for the program."""
+    with pytest.raises(SystemExit):
+        floss.main.main(["--print-completion", "fish"])
+
+    out = capsys.readouterr().out
+    assert "complete -c floss" in out
+
+
+@pytest.mark.parametrize("shell", ["badshell", ""])
+def test_print_completion_invalid_shell(shell, capsys):
+    """an unknown shell is an argument error, not a crash."""
+    assert floss.main.main(["--print-completion", shell]) == -1