.. Using_the_ykman_CLI.rst


.. _cli-label:

======================
Using the ykman CLI
======================

The ykman CLI can be used to configure all aspects of the YubiKey. This section covers the options for accessing and launching ykman CLI.

.. note:: ykman CLI is also called YubiKey Manager (CLI) and is separate from the YubiKey Manager GUI. The term YubiKey Manager is listed here as a literal to displayed text. 


.. _ykman-install-path-label:

Locate ykman CLI Installation Path 
===================================

The examples in this guide reference the default installation path. If you choose a different installation path, update the command to point to the path you used. 

To locate the ykman executable: 

1. Open a command line (Windows) or a terminal (MacOS). These commands work on both Windows and MacOS. The examples show a Windows prompt ``>``. The MacOS prompt is ``%``. 

2. Identify the ykman installation path:

   On Windows:

   .. code-block::

      >  where ykman
      >  Program Files\Yubico\YubiKey Manager CLI\ykman.exe
      >  Python311\Scripts\ykman.exe

   On MacOS:

   .. code-block::

      % where ykman
      /opt/homebrew/bin/ykman
      /opt/homebrew/bin/ykman
      /usr/local/bin/ykman

ykman CLI Version 
==================

Run the version command. 
If needed, change to the ykman directory. See :ref:`ykman-install-path-label`.

On Windows:

   .. code-block::

      > ykman -v
      YubiKey Manager (ykman) version: 5.4.0


On macOS
   .. code-block::

      % ykman -v
      YubiKey Manager (ykman) version: 5.4.0


Launch ykman CLI on Windows
============================

Run ``ykman`` commands from the command prompt. You do not need to specifically set PATH variables for ykman. 

Launch the ykman CLI through the command line, select and run the command using one of the options listed below. 


64-bit Systems 
---------------

  .. code-block::

     C:\>"C:\Program Files\Yubico\YubiKey Manager CLI\ykman.exe "


32-bit Systems
---------------

  .. code-block::

     C:\>"C:\Program Files (x86)\Yubico\YubiKey Manager CLI\ykman.exe "


Debug Logging Mode 
------------------

To launch ``ykman`` with **debug logging** enabled, add the following to the execution command:

.. code-block::

   --log-level DEBUG --log-file %USERPROFILE%\Desktop\ykman-log.txt

**Example**:

.. code-block::

   C:\>"C:\Program Files (x86)\Yubico\YubiKey Manager\ykman-gui.exe"
      --log-level DEBUG --log-file %USERPROFILE%\Desktop\
      ykman-log.txt



Launch ykman CLI on macOS
==========================

From the Mac Terminal application, run the listed commands as needed.

If you have installed ``ykman`` using Homebrew, as referenced in the :ref:`ykman-install-label` , you do not need to change directories to run ``ykman`` commands in Mac's terminal. The ykman CLI runs native commands natively.


Launch ykman CLI Mode 
----------------------

From the command line:

  .. code-block::

     % ykman


Launch ykman Debug Log Mode 
----------------------------

To run ``ykman`` with **debug logging** (to a file) enabled, add the following to the run command:

.. code-block::

   --log-level DEBUG --log-file /Users/<username>/Desktop/ykman.txt


Launch Issues
=============

PATH Issue
------------

If ykman did not start as expected, there might be a PATH issue. Run the command:

.. code-block::

   > ykman -v 


If you do not see the version you are expecting, you might have a PATH issue. Set the PATH variables to point to the correct version or run the ykman launch command from the ykman installation directory. 

Change Directory on MacOS 
--------------------------

Change directory to the location of the ykman executables. On macOS you must escape the  "space" in the filename "YubiKey Manager.app" by putting in a backslash before the space, or you must enclose the filename in double quotes. Examples of both are given below:

.. code-block::

   % cd /Applications/YubiKey\ Manager.app/Contents/MacOS/


.. code-block::

   %  cd "/Applications/YubiKey Manager.app/Contents/MacOS/"



----

Click for `Yubico Support <http://yubi.co/support>`_.