rename unpack->extract. Add CLI to README

README.rst

@@ -70,6 +70,7 @@ from scratch the latest version is recommended.
 .. csv-table::
     :header: "LittleFS Version", "Package Version", "LittleFS File System Version"
 
+    2.9.0, v0.11.X, 2.0 / 2.1 [#f1]_
     2.9.0, v0.10.X, 2.0 / 2.1 [#f1]_
     2.8.0, 0.8.X-0.9.X, 2.0 / 2.1 [#f1]_
     2.7.0, 0.7.X, 2.0 / 2.1 [#f1]_
@@ -92,6 +93,44 @@ on other platforms the source package is used and a compiler is required:
 + MacOS: Python 3.8 - 3.12 / x86_64, arm64
 + Windows: Python 3.8 - 3.12 / 32- & 64-bit
 
+CLI
+===
+littlefs-python comes bundled with a command-line tool, ``littlefs-python``, that can be used to create and extract littlefs binary images.
+
+.. code:: console
+
+   $ littlefs-python --help
+   usage: littlefs-python [-h] [--version] {create,extract,list} ...
+
+   Create, extract and inspect LittleFS filesystem images. Use one of the
+   commands listed below, the '-h' / '--help' option can be used on each command
+   to learn more about the usage.
+
+   optional arguments:
+     -h, --help            show this help message and exit
+     --version             show program's version number and exit
+
+   Available Commands:
+     {create,extract,list}
+       create              Create LittleFS image from file/directory contents.
+       extract             Extract LittleFS image contents to a directory.
+       list                List LittleFS image contents.
+
+To create a littlefs binary image:
+
+.. code:: console
+
+   # Creates a 1-megabyte "lfs.bin" containing README.rst
+   $ littlefs-python create README.rst lfs.bin --fs-size=1mb --block-size=4096
+
+   # Creates a 1-megabyte "lfs.bin" containing the contents of the examples/ folder
+   $ littlefs-python create examples lfs.bin --fs-size=1mb --block-size=4096
+
+To extract the contents of a littlefs binary image:
+
+.. code:: console
+
+   $ littlefs-python extract lfs.bin output/ --block-size=4096
 
 Development Setup
 =================

src/littlefs/__main__.py

@@ -50,7 +50,7 @@ def size_parser(size_str):
 
 
 def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
-    """Create LittleFS image from directory content"""
+    """Create LittleFS image from file/directory contents."""
     # fs_size OR block_count may be populated; make them consistent.
     if args.block_count is None:
         block_count = args.fs_size // args.block_size
@@ -69,9 +69,16 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
         print(f"  Image:       {args.destination}")
 
     source = Path(args.source).absolute()
+    if source.is_dir():
+        sources = source.rglob("*")
+        root = source
+    else:
+        sources = [source]
+        root = source.parent
+
     fs = _fs_from_args(args)
-    for path in source.rglob("*"):
-        rel_path = path.relative_to(source)
+    for path in sources:
+        rel_path = path.relative_to(root)
         if path.is_dir():
             if args.verbose:
                 print("Adding Directory:", rel_path)
@@ -88,7 +95,7 @@ def create(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
 
 
 def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
-    """List LittleFS image content"""
+    """List LittleFS image contents."""
     fs = _fs_from_args(args, mount=False)
     fs.context.buffer = bytearray(args.source.read_bytes())
     fs.mount()
@@ -112,8 +119,8 @@ def _list(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
     return 0
 
 
-def unpack(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
-    """Unpack LittleFS image to directory"""
+def extract(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
+    """Extract LittleFS image contents to a directory."""
     fs = _fs_from_args(args, mount=False)
     fs.context.buffer = bytearray(args.source.read_bytes())
     fs.mount()
@@ -197,7 +204,7 @@ def add_command(handler, name="", help=""):
     parser_create.add_argument(
         "source",
         type=Path,
-        help="Source directory of files to encode into a littlefs filesystem.",
+        help="Source file/directory-of-files to encode into a littlefs filesystem.",
     )
     parser_create.add_argument(
         "destination",
@@ -224,20 +231,20 @@ def add_command(handler, name="", help=""):
         help="LittleFS filesystem size. Accepts byte units; e.g. 1MB and 1048576 are equivalent.",
     )
 
-    parser_unpack = add_command(unpack)
-    parser_unpack.add_argument(
+    parser_extract = add_command(extract)
+    parser_extract.add_argument(
         "source",
         type=Path,
         help="Source LittleFS filesystem binary.",
     )
-    parser_unpack.add_argument(
+    parser_extract.add_argument(
         "destination",
         default=Path("."),
         nargs="?",
         type=Path,
         help="Destination directory. Defaults to current directory.",
     )
-    parser_unpack.add_argument(
+    parser_extract.add_argument(
         "--block-size",
         type=size_parser,
         required=True,