CLI for ease of testing.

Author: mmulqueen

docs/changelog.rst

@@ -4,6 +4,8 @@ Changelog
 0.12 — unreleased
 -----------------
 
+- New ``pystrich`` console script with a subcommand per format and PNG /
+  SVG / EPS / ASCII / terminal / DXF output. See :doc:`cli`.
 - Data Matrix: :class:`~pystrich.datamatrix.DataMatrixData` now expects
   either an ``encoding=`` argument or ``auto_encoding=True`` to be set
   on construction. The new ``auto_encoding=True`` flag picks the

docs/cli.rst

@@ -0,0 +1,65 @@
+Command-line interface
+======================
+
+Installing pyStrich exposes a ``pystrich`` console script with a subcommand
+per format and PNG / SVG / EPS / ASCII / terminal / DXF output.
+
+.. code-block:: console
+
+   $ pystrich qrcode --text "https://en.wikipedia.org/wiki/Jasper,_Missouri" -o jasper.svg
+   $ pystrich code128 --text "Dalton" -o dalton.png
+   $ pystrich ean13 --text "5050070007664" -o ean13.png
+   $ echo "DLB 573" | pystrich code39 -o code39.png
+   $ pystrich datamatrix --text "Rausschmeißer"   # terminal preview
+
+The last example produces:
+
+.. literalinclude:: examples/datamatrix-rausschmeisser-terminal.txt
+   :language: text
+   :class: terminal-art
+
+Reference
+---------
+
+.. argparse::
+   :module: pystrich.cli
+   :func: _build_parser
+   :prog: pystrich
+
+Format auto-detection
+---------------------
+
+The output format is auto-detected from the ``-o`` filename
+(``.png``, ``.svg``, ``.eps``, ``.dxf``); without ``-o`` it defaults to
+``terminal`` for 2D formats when stdout is a TTY. Piped or redirected
+output without an explicit ``-t`` is rejected, to avoid dumping binary
+into the next tool by accident.
+
+GS1 Data Matrix from the shell
+------------------------------
+
+GS1 Data Matrix uses ASCII with ``FNC1`` markers separating application
+identifiers and their values. ``--substitute-with-fnc1`` lets you build
+that input from a shell-friendly string:
+
+.. code-block:: console
+
+   $ pystrich datamatrix \
+       --text "|0105050070007664" \
+       --substitute-with-fnc1 "|" \
+       -o gs1.png
+
+See :doc:`datamatrix` for the full encoding discussion.
+
+Limitations
+-----------
+
+The CLI doesn't expose every Python-API knob. Reach for the Python API for
+1D label fonts, custom borders, EAN-13's ``first_digit_y_offset``, or the
+deprecated DataMatrix ``compat`` encoding.
+
+API
+---
+
+.. automodule:: pystrich.cli
+   :members: main

docs/conf.py

@@ -20,6 +20,7 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     "sphinx_copybutton",
+    "sphinxarg.ext",
 ]
 
 copybutton_prompt_text = r">>> |\.\.\. |\$ "
@@ -77,6 +78,12 @@ def _generate_example_images(app):
         DataMatrixEncoder(pystrich_url).get_terminal_art(ansi_bg=False),
         encoding="utf-8",
     )
+    (out / "datamatrix-rausschmeisser-terminal.txt").write_text(
+        DataMatrixEncoder(
+            DataMatrixData("Rausschmeißer", auto_encoding=True)
+        ).get_terminal_art(ansi_bg=False),
+        encoding="utf-8",
+    )
 
     if app.builder.name != "html":
         # Non-HTML builders parse .. image:: directives but don't render the

docs/index.rst

@@ -74,6 +74,7 @@ Guides
 .. toctree::
    :maxdepth: 1
 
+   cli
    recipes
    printing
 

docs/recipes.rst

@@ -3,6 +3,8 @@ Recipes
 
 Common patterns for using pyStrich in real applications.
 
+For one-off generation from a shell, see :doc:`cli`.
+
 Serving barcodes from a web request
 -----------------------------------
 

pyproject.toml

@@ -37,6 +37,9 @@ Homepage = "https://github.com/mmulqueen/pyStrich"
 Repository = "https://github.com/mmulqueen/pyStrich"
 Documentation = "https://www.method-b.uk/pyStrich/docs/"
 
+[project.scripts]
+pystrich = "pystrich.cli:main"
+
 [dependency-groups]
 dev = [
     "pytest>=8.2.2",
@@ -49,6 +52,7 @@ docs = [
     "sphinx>=8.1",
     "furo>=2024.8.6",
     "sphinx-copybutton>=0.5",
+    "sphinx-argparse>=0.5",
 ]
 
 [build-system]