Command-Line Interface: Preliminary Instructions

• Provide the Path to Your Bundle of Trusted CA Certificates
• Get the CLI and Its Plug-Ins
• Update the CLI Plug-Ins
• Create at Least One Profile
• Use Your Profile to Sign In
• Advanced: Create a Sign-In Script
• Advanced: Set Up a Shared Location

Provide the Path to Your Bundle of Trusted CA Certificates

If your SAS Viya platform deployment is enabled for Transport Layer Security (TLS), the machine where you will run the CLI must trust the certificate.

If you used a trusted root certificate authority (CA) to sign your certificates or your company’s signed certificate is already installed as a trusted root certificate on the machine where you will run the CLI, then the certificate should already be trusted and you do not need to proceed with the following steps.

Otherwise, make sure that the truststore has the root CA certificate and all the intermediate CA certificates. To retrieve the entire bundle of trusted root and intermediate CA certificates from your Kubernetes cluster:

1. Install the kubectl utility on the machine where you will run the CLI. See the Kubernetes documentation for more information.
2. Obtain a kubeconfig file from your Kubernetes cluster administrator.
3. Copy the trustedcerts.pem file from the pod to the local machine:

   kubectl -n name-of-namespace cp $(kubectl get pod -n name-of-namespace | grep "sas-logon-app" | head -1 | 
   awk -F" " '{print $1}'):security/trustedcerts.pem /tmp/trustedcerts.pem

4. On the machine where you will run the CLI, set the SSL_CERT_FILE environment variable.

   Here is an example on Linux:

   export SSL_CERT_FILE=/certificate-directory/trustedcerts.pem

For more information, see How To in SAS Viya Platform Encryption: Data in Motion.

Get the CLI and Its Plug-Ins

Here are the steps to download the CLI and install its plug-ins:

1. Go to the Support / Downloads and Hot Fixes page and download the appropriate file to your machine.
   Note: You must have a valid SAS profile on support.sas.com or on sas.com to download the CLI.
2. Prepare the downloaded file for your environment.

   Prepare the CLI Download File

   UNIX	Expand the file to a directory from which you plan to run the CLI: tar -xvzf /CLI-directory/sas-viya-cli-version-download-linux.tgz From the directory, make sure that the Execute permission is set: chmod +x sas-viya
   Windows or Macintosh	Unzip the file and place it in a directory from which you plan to run the CLI.

3. Navigate to the directory location where you saved the CLI file. You must run the CLI commands directly from this directory, or you can add this directory to your system path to make the CLI available to all CLI users.
4. Create a profile and sign in.
5. Install or display one or more plug-ins by running these commands:
   sas-viya plugins sas-viya plugins list sas-viya plugins list-repo-plugins sas-viya plugins install --repo SAS plugin-name sas-viya plugins install --repo SAS all

   1sas-viya plugins
   2sas-viya plugins list
   3sas-viya plugins list-repo-plugins
   4sas-viya plugins install --repo SAS plugin-name
   5sas-viya plugins install --repo SAS all

   1. Display the commands that are available to the CLI plug-ins command.
   2. Display the plug-ins that are currently installed.
   3. List the plug-ins in the SAS repository that are available for installing.
   4. Install a plug-in from the SAS repository.
   5. Install all plug-ins from the SAS repository.
   Note:

   • If one of the following characters precedes a plug-in name from the SAS repository, it means the following:

     SAS Repository Plug-in Preceding Character

     carat (^)	Means that the version of the plug-in in the SAS repository is more current than the version of the installed plug-in.
     asterisk (*)	Means that the version of the plug-in in the SAS repository is the same as the version of the installed plug-in.
     no preceding character	Means that the SAS repository plug-in is not installed.

   • Use ALL to download all plug-ins to the sas-viya CLI at one time. ALL is available only with the REPO option. It is available for download as of January 12, 2022, and is available for all previous versions of the sas-viya CLI.
   • The plug-ins are installed in the home directory of the user who ran the plugins command. Here is an example location: home-directory/.sas/viya-plugins.

Update the CLI Plug-Ins

Here are the steps to update one or all of the CLI plug-ins:

1. Navigate to the directory location where you saved the CLI file. You must run the CLI commands directly from this directory, or you can add this directory to your system path to make the CLI available to all CLI users.
2. Create a profile and sign in.
3. Update one of the CLI plug-ins by running this command:
   sas-viya plugins install --repo SAS plugin-name

   sas-viya plugins install --repo SAS plugin-name

4. Update all of the CLI plug-ins by running this command:
   sas-viya plugins install --repo SAS all

   sas-viya plugins install --repo SAS all

Create at Least One Profile

If you have not already created a profile for the environment that you want to use, complete the following steps.

1. Navigate to the directory on the machine that contains the CLI.
2. At the command prompt, enter a command to initialize a new profile. Here are examples:

   Initialize Profile

   To create a default profile, enter:	sas-viya profile init
   To create a profile called prod, enter:	sas-viya --profile prod profile init

   You can use a named profile to access different environments using the same set of CLIs. See Default Profile and Named Profiles for information about why you might want to use a named profile.

   Note: Running the PROFILE global command creates a config.json file in this directory: home-directory/.sas. For more information, see Overview.
3. Respond to the subsequent prompts as follows:

   Profile Initialization Prompts

   Service Endpoint	Specify the URL for the SAS Viya platform environment. Use the following format: communications-protocol://web-server-host-name:web-server-port Note: The port is required only if it is not the default port of 443. For example: https://host.example.com
   Output type	Specify your preferred format for CLI output (text, json, or fulljson). Note: For more information about the output types, see Output Type.
   Enable ANSI colored output	Specify whether to enable colored output (y or n).

4. Repeat steps 2 and 3 for any additional profiles that you want to create.

Use Your Profile to Sign In

1. Navigate to the directory on the machine that contains the CLI.
2. At the command prompt, enter a command to initiate the sign-in process. Here are examples:

   Sign In

   To use your default profile (assuming that the SAS_CLI_PROFILE environment variable is not set), enter:	sas-viya auth login
   To use a profile called prod, enter:	sas-viya --profile prod auth login

3. At the subsequent prompts, enter your user ID and password.

The authentication has a default timespan before it expires. See sas.logon.jwt in SAS Viya Platform: Configuration Reference for more information about the default expiry of an access token in SAS.

You can use the AUTH LOGOUT command to sign out.

Advanced: Create a Sign-In Script

You can use a batch script to create a profile and sign in. The following example is from a Linux environment.

CAUTION

The following example script includes a password. If you include a password in the script, you must secure it so that it can be read by only the administrator and the execution tools that use it.

#!/bin/sh

clidir=/CLI-directory

$clidir/sas-viya auth login --user userID --password password

Advanced: Set Up a Shared Location

Here are the steps to make the plug-ins available from a shared location:

1. Create a profile and sign in.
2. Navigate to the config.json file according to the operating system being used.

   CLI Directory for config.json File

   Linux	home-directory/.sas/viya-plugins
   Macintosh	home-directory/.sas/viya-plugins
   Windows	home-directory\.sas\viya-plugins

3. Open the config.json file. For each plug-in, find the line that contains the location, and modify the path to point to a shared location that contains the plug-ins directory. Here is an example of this section in the config.json file for the transfer plug-in:

   "transfer": {
         "location": "\shared-location\viya-plugins\sas-transfer-cli-version-20180330.1522434840.exe",
         "description": "tool for promoting contents across environments",
         "version": "1.3.5"

4. Propagate this change to the config.json file for all users.