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 |
|
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.
-
If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.
-
Download latest Conjur CLI archive file. For download links, see the Release Notes.
-
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'
-
To verify the Conjur CLI version, run
conjur --version
. -
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
-
If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.
-
Download the latest Conjur CLI archive file for your environment. For download links, see the Release Notes.
-
Extract the downloaded file.
tar -xvf conjur-cli-go_8.0.1_<version>.tar.gz
-
Give execute permissions to the conjur executable:
chmod +x conjur
-
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:
-
Update your system's RC file (for example, .bashrc or .zshrc):
PATH="/path/to/conjur/cli:$PATH"
-
Force reload:
source ~/<RC file>
-
-
-
To verify the Conjur CLI version, run
conjur --version
.Alternatively, run
./conjur --version
from the location of the executable. -
Delete the archive file.
-
If you have an earlier version of the Conjur CLI installed, uninstall it. For details, see Uninstall the Conjur CLI.
-
Download latest Conjur CLI, archive file. For download links, see the Release Notes.
-
Extract the downloaded file.
tar -xvf conjur-cli-go_8.0.1_<version>.tar.gz
-
Give execute permissions to the conjur executable:
chmod +x conjur
-
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:
-
Update your system's RC file (for example, .bashrc or .zshrc):
PATH="/path/to/conjur/cli:$PATH"
-
Force reload:
source ~/<RC file>
-
-
-
To verify the Conjur CLI version, in the Terminal run
conjur --version
.Alternatively, run
./conjur --version
from the location of the executable. -
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.
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 withhttps://
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
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
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
| ||
macOS | Apple macOS keychain |