CodeScene CLI tool
==================

What You Can Do With The CLI
----------------------------

.. include:: ../../shared/cli/value-and-use-cases.rst

Install The CLI
---------------

.. include:: ../../shared/cli/binary-installation.rst

Authenticate The CLI
--------------------

For interactive use, set the CodeScene URL and sign in with your account. The command opens a browser for login and stores a refreshable session locally. The CLI refreshes the session automatically. Sign in again if the session expires, or revoke it from :doc:`../configuration/oauth2-authorizations`.

.. code-block:: console

    export CS_ONPREM_URL=<https://your.codescene.com>
    cs auth login

Use ``--no-browser`` when the CLI cannot open a browser, for example in an SSH session or on a headless machine. It prints a login URL that you can open in a browser on this or another computer:

.. code-block:: console

    cs auth login --no-browser

Check the stored session, or sign out:

.. code-block:: console

    cs auth status
    cs auth logout

For CI or other non-interactive environments, use a user with a Technical role - see :doc:`../configuration/users-and-roles`. Create a Personal Access Token at `https://your.codescene.com/configuration/user/token`.

Set the environment variables as follows:

.. code-block:: console

    export CS_ONPREM_URL=<https://your.codescene.com>
    export CS_ACCESS_TOKEN=<your-token>

Or in Windows PowerShell:

.. code-block:: console

    $env:CS_ONPREM_URL = '<https://your.codescene.com>'
    $env:CS_ACCESS_TOKEN = '<your-token>'

Windows setup options
~~~~~~~~~~~~~~~~~~~~~

Windows Command Prompt (temporary, current session):

.. code-block:: console

    SET CS_ACCESS_TOKEN=<your-token>
    SET CS_ONPREM_URL=<https://your.codescene.com>

Windows Command Prompt (persistent):

.. code-block:: console

    SETX CS_ACCESS_TOKEN=<your-token>
    SETX CS_ONPREM_URL=<https://your.codescene.com>

You can also set variables through System Properties:

1. Right-click "This PC" or "My Computer"
2. Click "Properties"
3. Click "Advanced system settings"
4. Click "Environment Variables"

Shortcut:

1. Press ``Windows + R``
2. Type ``sysdm.cpl``
3. Go to the "Advanced" tab
4. Click "Environment Variables"

Off-line use
------------

Once the CLI tool has successfully authenticated with the server once, it can be used offline until the end of the server's license period. The offline license is stored in the directory defined by the ``CODESCENE_HOME`` environment variable. If you want to run offline in builds such as GitHub Actions, you can copy this folder into the Docker image.

If environment variable ``CODESCENE_HOME`` is not set:

- in Windows it is ``$APP_DATA/Codescene``
- else it is ``.codescene`` directory in user home directory

Command Guides And Reference
----------------------------

.. toctree::
  :maxdepth: 1

  command-reference
