======================
Command-line interface
======================

Hy provides a handful of command-line programs for working with Hy code.

.. contents:: Contents
   :local:

.. _hy-cli:

hy
--

``hy`` is a command-line interface for Hy that in general imitates the program
``python`` provided by CPython. For example, ``hy`` without arguments launches
the :ref:`REPL <repl>` if standard input is a TTY and runs the standard input
as a script otherwise, whereas ``hy foo.hy a b`` runs the Hy program
``foo.hy`` with ``a`` and ``b`` as command-line arguments. See ``hy --help``
for a complete list of options and :py:ref:`Python's documentation
<using-on-cmdline>` for many details. Here are some Hy-specific details:

.. cmdoption:: -m <module>

   Much like Python's ``-m``, but the input module name will be :ref:`mangled
   <mangling>`.

.. cmdoption:: --spy

   Print equivalent Python code before executing each piece of Hy code in the
   REPL::

       => (+ 1 2)
       1 + 2
       ------------------------------
       3

.. cmdoption:: --repl-output-fn

   Set the :ref:`REPL output function <repl-output-function>`. This can be the
   name of a Python builtin, most likely ``repr``, or a dotted name like
   ``foo.bar.baz``. In the latter case, Hy will attempt to import the named
   object with code like ``(import foo.bar [baz])``.


.. _hy2py:

hy2py
-----

``hy2py`` is a program to convert Hy source code into Python source code. Use ``hy2py --help`` for usage instructions. It can take its input from standard input, or from a file or module name provided as a command-line argument. In the case of a module name, the current working directory should be the parent directory of that module, and the output parameter (``--output/-o``) is required. When the output parameter is provided, the output will be written into the given folder or file. Otherwise, the result is written to standard output.

    .. warning::
       ``hy2py`` can execute arbitrary code (via macros, :hy:func:`eval-when-compile`, etc.). Don't give it untrusted input.

Hy has no built-in capacity to translate Python to Hy, but see `py2hy <https://github.com/hylang/py2hy>`__.

.. _hyc:

hyc
---

``hyc`` is a program to compile files of Hy code into Python bytecode. Use ``hyc --help`` for usage instructions. The generated bytecode files are named and placed according to the usual scheme of your Python executable, as indicated by :py:func:`importlib.util.cache_from_source`.

    .. warning::
       ``hyc`` can execute arbitrary code (via macros, :hy:func:`eval-when-compile`, etc.). Don't give it untrusted input.
