.. Using_the_ykman_CLI.rst


.. _cli-label:

===================================================
Using the YubiKey Manager CLI
===================================================

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


Windows
=========

Run the commands from Command Prompt or PowerShell. **Either** facilitate the running of ``ykman`` commands, **or** if your environment variable is not set to automatically find ``ykman``, change directories. Instructions for both are given below.


Facilite Running ykman Commands
-------------------------------

To enable running ``ykman`` commands without changing directories or updating environment variables, add an alias for ``ykman`` to your $PROFILE for PowerShell. To do this, run the following commands in PowerShell.

:Step 1: Test for $PROFILE existence - output should return true

         .. code-block::

            PS> Test-Path $PROFILE

:Step 2: If ``False`` is returned, make a $PROFILE

         .. code-block::

            PS> New-Item $PROFILE -ItemType File

:Step 3: Create alias for ``ykman`` CLI, (32-bit)

         .. code-block::

            PS> Add-Content $PROFILE -Value 'Set-Alias ykman "C:\Program Files (x86)\Yubico\YubiKey Manager\ykman.exe"'

:Step 4: Create alias for ``ykman`` CLI, (64-bit)

         .. code-block::

            PS> Add-Content $PROFILE -Value 'Set-Alias ykman "C:\Program Files\Yubico\YubiKey Manager\ykman.exe"'

:Step 5: Reload $PROFILE by closing and re-opening PowerShell, or run the command

         .. code-block::

            PS> & $PROFILE


Change Directory
-------------------

If your environment variable is not set to automatically find ``ykman``, or you don't have a PowerShell alias set, change directory to the location of the ``ykman`` executables. For example, with Windows 64-bit version of YubiKey Manager installed, this would be ``C:\\cd "C:\Program Files\Yubico\YubiKey Manager\"``.


Launch ykman
---------------

You might need to scroll horizontally to see the entire command.

To launch ``ykman`` in GUI mode or CLI mode from the command line, select and run the command for one of the options listed below:

* Launch ``ykman`` **CLI**, (**32-bit**)

  .. code-block::

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

* Launch ``ykman`` **CLI**, (**64-bit**)

  .. code-block::

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

* Launch ``ykman`` **GUI**, (**32-bit**)

  .. code-block::

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

* Launch ``ykman`` **GUI**, (**64-bit**)

  .. code-block::

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

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


macOS
======

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

If you have installed ``ykman`` using Homebrew, referenced in the `ykman Installation for MacOS <https://docs.yubico.com/software/yubikey/tools/ykman/Install_ykman.html#macos>`_, you don't need to change directories to run ``ykman`` commands in Mac's terminal. The CLI will run as native commands.


Change Directory
------------------

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/"



Launch ykman
------------


You might need to scroll horizontally to see the entire command.

To launch ``ykman`` in GUI mode or CLI mode from the command line, run the command for the appropriate option:

* Launch ``ykman`` **CLI**

  .. code-block::

     % /Applications/YubiKey Manager.app/Contents/MacOS/ykman

* Launch ``ykman`` **GUI**

.. code-block::

   % /Applications/YubiKey Manager.app/Contents/MacOS/ykman-gui

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

.. code-block::

   --log-level DEBUG --log-file ~/Desktop/ykman.txt

**Example**:

.. code-block::

   % /Applications/YubiKey Manager.app/Contents/MacOS/ykman --log-level DEBUG --log-file ~/Desktop/ykman.txt



----

To get in touch with Yubico Support, `click here <http://yubi.co/support>`_.