Set up the Conjur CLI

This topic describes how to set up the Conjur CLI v8.x.

FIPS-enabled machines support only Conjur CLI v7.x and later.

The Conjur CLI implements the Conjur REST API, providing an alternate interface for managing Conjur resources, including roles, privileges, policy, and secrets.

System requirements

This section describes the system requirements for Conjur CLI v8.x.

Supported platforms

  • Windows 10 or later

  • Red Hat Enterprise Linux 7, 8, 9

  • macOS Catalina or later

Supported Conjur version

Conjur Enterprise v12.9 and later

Install the Conjur CLI

This section describes how to install the Conjur CLI.

  • If you are using the Conjur Docker image, the Conjur CLI is automatically included with the image. For more information, see Use the Conjur CLI in Docker.
  • Conjur CLI v8.x does not support installation from PIP.
All Conjur artifacts are cryptographically signed archives. We strongly recommend verifying archive signatures before installing them in your environment. For more information, see Verify signed Conjur artifacts.

  1. If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.

  2. Download latest Conjur CLI archive file. For download links, see the Release Notes.

  3. Recommended: To enable running the Conjur CLI from anywhere on your machine, add the path to the folder containing the conjur executable to your system's PATH environment variable.

    You can set PATH globally using the Windows Environment Variables configuration, which can be accessed by searching for 'path'

  4. To verify the Conjur CLI version, run conjur --version.

  5. Delete the archive file.

Use the installation method appropriate for your environment:

Run the following command:

sudo rpm -i conjur-cli-go_8.0.1_amd64.rpm

Run the following command:

sudo dpkg -i ./conjur-cli-go_8.0.1_amd64.deb

  1. If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.

  2. Download the latest Conjur CLI archive file for your environment. For download links, see the Release Notes.

  3. Extract the downloaded file.

      
    tar -xvf conjur-cli-go_8.0.1_<version>.tar.gz

  4. Give execute permissions to the conjur executable:

      
    chmod +x conjur

  5. Recommended: To enable running the Conjur CLI from anywhere on your machine, do one of the following:

    • Move the conjur executable to your machine's /usr/local/bin directory:

        
      $ sudo mv conjur /usr/local/bin

    • Update your system's PATH variable with the path to the folder containing the conjur executable:

      1. Update your system's RC file (for example, .bashrc or .zshrc):

          
        PATH="/path/to/conjur/cli:$PATH"

      2. Force reload:

          
        source ~/<RC file>

  6. To verify the Conjur CLI version, run conjur --version.

    Alternatively, run ./conjur --version from the location of the executable.

  7. Delete the archive file.

  1. If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.

  2. Download latest Conjur CLI, archive file. For download links, see the Release Notes.

  3. Extract the downloaded file.

      
    tar -xvf conjur-cli-go_8.0.1_<version>.tar.gz

  4. Give execute permissions to the conjur executable:

      
    chmod +x conjur

  5. Recommended: To enable running the Conjur CLI from anywhere on your machine, do one of the following:

    • Move the conjur executable to your machine's /usr/local/bin directory:

        
      $ sudo mv conjur /usr/local/bin

    • Update your system's PATH variable with the path to the folder containing the conjur executable:

      1. Update your system's RC file (for example, .bashrc or .zshrc):

          
        PATH="/path/to/conjur/cli:$PATH"

      2. Force reload:

          
        source ~/<RC file>

  6. To verify the Conjur CLI version, in the Terminal run conjur --version.

    Alternatively, run ./conjur --version from the location of the executable.

  7. Delete the archive file.

Use the following commands to install the Conjur CLI in a MacOS environment using Homebrew:

brew tap cyberark/tools
brew update
brew install conjur-cli

Use the Conjur CLI in Docker

Conjur CLI v8.x is included in the Docker image for Conjur Enterprise v13.x and later.

Run Conjur CLI commands in Docker

Use the following command to run Conjur CLI commands using Docker:

$ docker run --rm -it cyberark/conjur-cli:8 <CLI command>

Persist Conjur CLI connection data for Docker

Docker containers do not store state after the container exits. Any initialization you do or files you create are permanently discarded when you exit the shell. Changes you make to the Conjur server are preserved.

You can use a folder in your file system to persist the data that the Conjur CLI uses to connect. For example:

$ mkdir mydata
$ chmod 700 mydata
$ docker run --rm -it -v $(PWD)/mydata:/root cyberark/conjur-cli:8 init -u https://my-conjur-server -a myAccount
$ ls -A mydata
.conjurrc conjur-server.pem
$ docker run --rm -it -v $(PWD)/mydata:/root cyberark/conjur-cli:8 login -i admin
Please enter admin's password (it will not be echoed): 
Logged in
$ ls -A mydata
.conjurrc .netrc conjur-server.pem

You can use a shell alias to make it easier to persist the connection data. For example:

$ alias conjur='docker run --rm -it -v $(PWD)/mydata:/root cyberark/conjur-cli:8'

After you configure the shell alias, you can use the Conjur CLI as follows:

$ conjur whoami

The file .netrc, when created or updated by conjur login, contains a user identity credential that can be used to access the Conjur API. We strongly recommend that you either remove the .netrc file after use or otherwise secure it like you would another .netrc file.

Limitations of using the Conjur CLI in Docker

  • When you use the Conjur CLI with Docker, credentials can be stored in a file only and not in the native operating system keychain.

  • OIDC authentication is not supported in Docker.

Configure Conjur CLI access to Conjur

To start using the Conjur CLI to interface with Conjur:

When you run the Conjur CLI for the first time, the initial setup of the CLI might take a few moments. After that, all commands should run seamlessly.

  1. Initialize the Conjur CLI

    Provide the details of the Conjur server that you are working with (see init). For instructions on using OIDC to authenticate to the Conjur CLI, see OIDC Authenticator for Conjur UI and Conjur CLI authentication.

     
    conjur init --url https://<conjur-server-endpoint>

    where conjur-server-endpoint is the URL of the Conjur server, beginning with https://

  2. Authenticate to Conjur

    Log in to Conjur using your user credentials or the Conjur admin user. For more login options and information see login.

     
    conjur login

    3. Enter credentials (username and password) when prompted. Your credentials are saved to the operating system's credential store by default, or to the netrc file if there is no credential store. For more information, see Credential store below.

Credential store

When you log in to the Conjur CLI, your login credentials (username and password) are stored in the system's native credential store by default.

When the supported credential store for your platform is not native on your machine, or is not accessible, the Conjur CLI writes your credentials in plaintext to a config file (netrc) on the machine. In this case, for security purposes we strongly recommend that you log out of the CLI (conjur logout) when you are not using it. Logging out removes the credentials from the netrc file.

Supported credential stores

Platform

Supported Credentials store

Windows

Windows Credential Locker/Password Vault

RHEL

Free Desktop Secret Service

 

  • We strongly recommend that you install a credential store when working with RHEL.

  • RHEL servers that have only a command-line interface (no GUI) do not come with a native credential store. In this case, you must configure your environment to allow the Conjur CLI to save credentials to the Secret Service keyring backend. Make sure you have the following on the machine:

    • GNOME Keyring with a Secret Service backend

    • A running D-Bus session

    • An unlocked store

macOS

Apple macOS keychain