BookmarkSubscribeRSS Feed

SAS Viya Command-Line Interface for Administration (update)

Started ‎11-18-2021 by
Modified ‎11-18-2021 by
Views 8,199

SAS Viya includes a set of command-line interfaces that Viya administrators will find extremely useful. The command-line interfaces(CLI)  allow administrators to perform numerous administrative tasks in batch as an alternative to using the SAS Environment Manager interface. In addition, calls to the CLI's can be chained together in scripts to automate more complex administration tasks. In this post, I will take a look at a few useful examples. (NOTE: this post is an update of the previous post on the Viya 3.x sas-admin CLI)

 

In Viya 3.x the command-line interface was sas-admin. In SAS Viya 4 the command-line interface:

 

  • is called sas-viya
  • consolidates all existing Viya command-line interfaces in one location.

 

The sas-viya command-line interface will run on Linux, Windows, or OSX and is available for download from support.sas.com

 

The sas-viya CLI is the main interface, it acts as a wrapper for the provided plugins. The individual plug-ins operate as interfaces to administration functionality in Viya. The CLI's provide a simplified interface to the SAS Viya REST services, they abstract the functionality of the REST services allowing an administrator to enter commands on a command line and receive a response back from the system.

 

Installing

To install the CLI you download it from support.sas.com. Once you have the executable you need to install any plug-ins that you want to use. Plug-ins are installed from a repository. To see what repository you are configured to use, run the command.

 

sas-viya plugins list-repos

 

gn_1-viya-cli_02.png

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

 

This is the default SAS hosted repository.

 

If you navigate to the URL http://support.sas.com/repos/viyacli/ you can see information on the plug-ins available in the repository. You can check the status of your locally installed plug-ins using the following command.

 

sas-viya plugins list-repo-plugins

 

gn_2-viya-cli_01.png

 

The command outputs all the plug-ins available in the repository and also compares them to the plugins installed locally. In the output of the command plug-ins are flagged with an indicator that reflects their status:

 

  • asterix( *) : plugin is installed locally and the version in the repository is the same as the version installed
  • accent (^): plugin is installed locally and the version in the repository is more recent than the version installed
  • no indicator the plugin is available in the repository but has not been installed locally.

 

Check out this article to see how to install all available plug-ins (it covers sas-admin but the details are the same for sas-viya).

 

Using

With the plug-ins installed there are two preliminary steps required to use the command-line interface you need to:

 

  • create a profile: 
  • authenticate to Viya

 

To create a default profile:

 

sas-viya profile set-endpoint "http://gelcorp.pdcesx*****.race.sas.com"

sas-viya profile set-output json

 

You can also create named profiles to connect to different Viya Environments.  

 

Profiles are stored in the user's home directory in a file <homedir>/.sas/config.json and contain the endpoint of the Viya environment to connect to and the output setting.

 

gn_3-viya-cli.png

 

The output options range from text, which provides a simplified text output of the result to fulljson which provides the full JSON output that is returned by the REST calls that the CLI submits.

 

To authenticate:

 

sas-viya auth login --user sasadm --password ********

The authentication step creates a token in a file stored in the user's home directory which is valid for, by default, 10 hours.  The file location is <homedir>/.sas/credentials.json. If you don't want to hard-code the userid and password you can use the .authinfo file approach to store your credentials described here.

 

The syntax of a call to the sas-viya CLI is shown below. The CLI  requires a plugin and command, and potentially a sub-command, options, and arguments. The example shows a call to the identities plugin. This command will list all the users who are members of the SAS Administrators custom group.

 

In this execution of sas-viya:

 

  • the plug-in is identities
  • there is a global option --output set so that the result is returned in basic text
  • the command is list-members
  • the command option --group-id specifies the group whose members you wish to list.

 

gn_4-viya-cli_05.png

 

The built-in help of the CLI's is a very useful feature.

 

./sas-viya --help

 

This command provides help on the commands and the plugins available, and the global options that may be used.

 

gn_5-viya-cli_03.png

 

You can also display help on the specific plugins by adding the plugin name and then specifying --help.

 

./sas-viya authorization --help

 

gn_6-viya-cli_04.png

 

A simple example

Let's look at an example of using the command-line interface to perform some common administrative tasks. In the example we will create:

 

  • a new folder that is the sub-folder of an existing folder
  • secure the folder
  • import some existing content
  • create and secure a CAS Library
  • Load data into memory

 

Many of the folders commands require the ID from the previous request. The id of the item is displayed when you create the items and also when you list them using the CLI. In the examples, we will use JQ to capture pars the JSON output of one command and pass the result on to a subsequent command.

 

Create a folder

Create a new folder at the root of the folder tree.

 

sas-viya folders create --name gelcontent

gn_7-viya-cli_08-2.png

 

Create a sub-folder

The next step is to create a folder that is a sub-folder of the /gelcontent folder. The id of the parent folder and the name of the new folder is passed to the create command of the folders plugin.

 

sas-viya --output json folders create --description "Sales" --name "Sales" --parent-path /gelcontent

 gn_8-viya-cli_06.png

 

Set permissions on the folder

Next using the folder plugin to retrieve the folder id from the previous step set authorization on the folder. In this call to the authorization plug-in, we grant full control to the group Sales on the new folder and its content.

 

folderid=$(sas-viya --output json folders show --path /gelcontent | jq -r '.["id"]')

sas-viya --output json authorization create-rule grant --permissions read,create,update,delete,add,remove,secure --group Sales --object-uri /folders/folders/${folderid}/** --container-uri /folders/folders/${folderid}

 

gn_9-viya-cli_10.png

 

In SAS Environment Manager check that the folder has been created and check the authorization settings. The authorization setting on the folder shows that a new rule has been created and applied to provide full access to Sales.

gn_10-viya-cli_11-1024x436.png

 

Import a content to the folder

The transfer CLI allows us to import and export content from a Viya Environment. In this step we will

 

  • upload a transfer package that contains content
  • import the package
  • list the contents of the folder with the content

 

#upload the package to Viya and capture the packagedid
packageid=$(sas-viya --output json transfer upload --file /tmp/viya4packages/gelcontent_sales_reports.json | jq | jq -r '.["id"]')
echo ID of the uploaded package is $packageid
#import the package using the id
sas-viya  --output text transfer import --id $packageid

 

gn_11-viya-cli_14.png

 

View the folders and their content.

 

sas-viya --output text folders list-members --path /gelcontent/Sales --recursive --tree

 

gn_12-viya-cli_15.png

 

 

Create a CASLIB and set permissions

The next task we might perform is to add a caslib, set authorization and load data. We can do that with the following calls to the CAS plugin.

 

sas-viya --output text cas caslibs create path --name salesdl --path /gelcontent/gelcorp/sales/data --server cas-shared-default

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant ReadInfo

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant Select

sas-viya --output text cas caslibs add-control --server cas-shared-default --caslib salesdl --group Sales --grant LimitedPromote

gn_13-viya-cli_12-1024x303.png

 

Load data into memory

Load all the tables in the caslibs path into memory.

 

sas-viya --output text cas tables load --table=* --server cas-shared-default --caslib salesdl

gn_14-viya-cli_13-1024x54.png

 

Conclusion

The SAS Viya command-line interfaces provide an extremely useful set of functionality in support of automating common administration tasks. There is obviously much more that can be done with the CLI's than we can cover in this blog. For more information and details of the available interfaces please check out the following resources (some refer to sas-admin but the details remain the same):

 

 

 

Find more articles from SAS Global Enablement and Learning here.

Version history
Last update:
‎11-18-2021 09:35 AM
Updated by:
Contributors

SAS Innovate 2025: Register Now

Registration is now open for SAS Innovate 2025 , our biggest and most exciting global event of the year! Join us in Orlando, FL, May 6-9.
Sign up by Dec. 31 to get the 2024 rate of just $495.
Register now!

Free course: Data Literacy Essentials

Data Literacy is for all, even absolute beginners. Jump on board with this free e-learning  and boost your career prospects.

Get Started