.. _cli-install:

==================================
Installing and Configuring the CLI
==================================
The |confluent-cli| is supported for macOS, Microsoft Windows, and Linux operating systems. You can install the
|confluent-cli| by downloading the executable or tarball.

---------------------
Scripted installation
---------------------

.. include:: ../quickstart/includes/quickstart-step3.rst
    :start-after: step-3-run-another-instance-end
    :end-before: step-3-install-cli-end

--------------------
Tarball installation
--------------------
Download and install the raw binaries by platform.

- `Darwin/x64 <https://s3-us-west-2.amazonaws.com/confluent.cloud/confluent-cli/archives/latest/confluent_latest_darwin_amd64.tar.gz>`_
- `Windows/x64 <https://s3-us-west-2.amazonaws.com/confluent.cloud/confluent-cli/archives/latest/confluent_latest_windows_amd64.zip>`_
- `Linux/x64 <https://s3-us-west-2.amazonaws.com/confluent.cloud/confluent-cli/archives/latest/confluent_latest_linux_amd64.tar.gz>`_
- `Linux/386 <https://s3-us-west-2.amazonaws.com/confluent.cloud/confluent-cli/archives/latest/confluent_latest_linux_386.tar.gz>`_
- `Checksums (operating system agnostic) <https://s3-us-west-2.amazonaws.com/confluent.cloud/confluent-cli/archives/latest/confluent_latest_checksums.txt>`_

.. _confluent-cli-jdk-req:

-------------------------
Java version requirements
-------------------------

On non-Windows platforms, the |confluent-cli| offers :ref:`confluent_local` commands
(designed to operate on a local install of |cp|) which require Java, and JDK version ``1.8`` or
``1.11`` is recommended. If you have multiple versions of Java installed, set
JAVA_HOME to the version you want |cp| to use. 

.. important:: 

  Setting JAVA_HOME when you have multiple JDKs prevents the |confluent-cli| from defaulting to the newest installed Java version, which may not be supported. If the default Java version is not supported, the CLI will fail with a message about unsupported Java versions even if a supported version is installed and set as the in-use JDK (shown as output to ``java -version``).

* To set JAVA_HOME, add the location of a supported JDK to your PATH in a file such as ``.bash_profile`` or by setting it temporarily as an environment variable in your current shell:

  .. code:: bash

    export JAVA_HOME=<path-to-JDK-home>

  For example:

  .. code:: bash

    export JAVA_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home/

* To find the location of your installed Java versions, type the following in a command shell:

  .. code:: bash

    /usr/libexec/java_home -V

  The output will look similar to this example, which happens to show two JDKs, ``12.0.1`` and ``1.8.0_212``:

  .. code:: bash

    /usr/libexec/java_home -V
    Matching Java Virtual Machines (2):
        12.0.1, x86_64:	"OpenJDK 12.0.1"	/Library/Java/JavaVirtualMachines/openjdk-12.0.1.jdk/Contents/Home
        1.8.0_212, x86_64:	"AdoptOpenJDK 8"	/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home
        
  In this case, you would add JDK ``1.8`` to your ``.bash_profile``:

  .. code:: bash

    #JAVA_HOME
    export JAVA_HOME=/Library/Java/JavaVirtualMachines/adoptopenjdk-8.jdk/Contents/Home/

  The |confluent-cli| will then run with the specified, supported JDK ``1.8``, regardless of how many Java versions you have installed.
  
  See also, :ref:`Java supported versions for Confluent Platform<java-sys-req>`.

----------
Next steps
----------

-   Type ``confluent`` in your terminal to get started.

    ::

        confluent

    You should see |confluent-cli| usage information:

    ::

        Manage your Confluent Platform.

        Usage:
          confluent [command]

        Available Commands:
          completion  Print shell completion code.
          help        Help about any command
          iam         Manage RBAC and IAM permissions.
          local       Manage a local Confluent Platform development environment.
          login       Log in to Confluent Platform. This is required for RBAC.
          logout      Log out of Confluent Platform.
          secret      Manage secrets for Confluent Platform.
          update      Update the confluent CLI.
          version     Print the confluent CLI version.

        Flags:
          -h, --help            help for confluent
          -v, --verbose count   Increase verbosity (-v for warn, -vv for info, -vvv for debug, -vvvv for trace).
              --version         version for confluent

        Use "confluent [command] --help" for more information about a command.

-   Set your PATH variable:

    ::

       export PATH=<path-to-confluent>/bin:${PATH};

-   If |rbac| is enabled, you must log in to the |confluent-cli| with the Metadata service URL specified (``<url>``). For
    more information, see :ref:`confluent_login`.

    ::

        confluent login --url <url>

    ::

        Enter your Confluent credentials:
        Email:
        Password:

    Your output should resemble:

    ::

        Logged in as user

-  Try out the |confluent-cli| using a :ref:`local development <confluent_local>` environment.