Command Line Interface

Start using the CLI

The SailPoint CLI is a terminal-based tool you can use to to interact with your SailPoint Human Fabric (SHF) tenant. The CLI provides a text-based environment you can use to run operations known as "commands" to interact with your tenant however you want.

You can use the CLI to perform many functions you would have otherwise used Postman or custom scripts to perform before. For example, you can use the CLI to call the SailPoint APIs to do whatever you want in your SHF tenant, and you can do all this directly on the command line, with minimal setup.

Learn how to use the SailPoint command line interface (CLI) in this guide.

Contents

• Start using the CLI
• Contents
• Get the CLI
  • Windows
  • MacOS
  • Linux
    • Deb Package
    • RPM Package
• Configuration
  • OAuth Authentication
  • PAT Authentication
  • Troubleshooting configuration
• Environment variable configuration
• Usage
• Support
• Contribution
• Questions

Get the CLI

To install the SailPoint CLI: use a package manager for the OS of your choice. Prebuilt binaries for OS X, Windows, and Linux are provided in each release.

Windows

info

Note this installer is only compatible with 64 bit Windows.

Download the latest release from the releases page. The release should include an MSI file named sail_x.x.x_windows_amd64.msi that can be installed on Windows, with x.x.x being the version of the most recent release.

To install the MSI file, double click on it and follow the prompts in the installer.

MacOS

MacOS users can use Homebrew to install the CLI. Run these commands in your terminal:

brew install sailpoint-oss/tap/sailpoint-cli

Then make sure you can run the sail command.

Linux

Each release on the releases page includes a tarball that can be extracted and run on Linux. Or you can install using the available .deb or .rpm packages.

Deb package

Download the specific .deb package from the release you wish to install

Then install it using one of the following commands, with the x.x.x being the version of the most recent release.

sudo apt install ./sail_x.x.x_linux_amd64.deb

sudo apt install /path/to/deb/package/sail_x.x.x_linux_amd64.deb

RPM package

Download the specific .rpm package from the release you wish to install

Then install it using one of the following commands, with the x.x.x being the version of the most recent release.

sudo yum localinstall ./sail_x.x.x_linux_amd64.rpm

sudo yum localinstall /path/to/rpm/package/sail_x.x.x_linux_amd64.rpm

Configuration

To configure the CLI to connect and authenticate to your SHF tenant, you must do the following:

• Find your tenant name or tenant URL. To learn how to find it, refer to Getting Started. The CLI will use this value to connect to your SHF instance.
• Choose an authentication method:
  • OAuth | Sign in through your browser. You do not need to create credentials first.
  • PAT | Create a personal access token (PAT). Make sure to note the "Client ID" and "Client Secret." The CLI needs this information to authenticate successfully. To learn how to create a PAT, refer to Personal Access Tokens.

To configure your first environment, run the following command:

sail env create {environment}

with {environment} being the name of the environment you wish to configure. If you do not provide a name, the CLI uses your tenant name as the environment name.

The CLI asks for your tenant name or URL. You can enter either of these:

• Your tenant name, such as acme. The CLI uses the default identitynow.com domain.
• Your tenant URL, such as https://acme.identitynow-demo.com. Use this option for tenants that are not on the default identitynow.com domain. You can also paste the API URL or a URL copied from your browser, such as https://acme.identitynow-demo.com/ui/d/dashboard. The URL must use HTTPS.

From this value, the CLI creates two URLs:

• The Tenant URL - The web URL used to access your SailPoint Human Fabric tenant (ex. https://tenant.identitynow.com), this is used during the OAuth process.
• The API URL - The API URL used to access your SailPoint Human Fabric tenant (ex. https://tenant.api.identitynow.com), this is used for the api calls made by certain commands.

The CLI then checks the API URL with your tenant. If the check passes, the CLI skips the URL confirmation prompts:

sail env create
Tenant name or URL (ie: acme, or https://acme.identitynow-demo.com): () https://acme.identitynow-demo.com/

✔ Found tenant at https://acme.identitynow-demo.com (API: https://acme.api.identitynow-demo.com)

If the check fails, the CLI shows a warning and asks you to correct the Tenant URL and the API URL. Make sure that the URLs match your tenant and try again. If the CLI shows the Could not confirm the tenant API URL warning again, the URLs are likely incorrect. Run sail env update {environment} to fix them before you use the environment.

To change the URLs of an existing environment, run sail env update {environment}. Press enter at the tenant prompt to keep the URLs that are already stored.

Then choose the authentication type for the environment: oauth or pat.

OAuth authentication

With the default environment values populated you can immediately begin using the CLI with OAuth authentication. Just make sure OAuth is your selected authentication method, this can be done by running sail set auth oauth.

The CLI runs the authorization code flow with PKCE, and it exchanges the code with your tenant directly. These are the steps:

1. The CLI opens your browser and prints a confirmation code, such as Ab3d-9Kx1.

2. You sign in to Identity Security Cloud.

3. The page at https://developer.sailpoint.com/sailapps shows the same confirmation code and a one-time code that starts with sp1.. Make sure that both confirmation codes match.

4. You copy the one-time code and paste it into the CLI prompt.

The CLI refuses the one-time code if it belongs to a different sign-in attempt. Paste the code only into the CLI window that started sign-in.

info

OAuth login needs an interactive terminal, because you must paste the code. Use a personal access token in a pipeline or in any other non-interactive session.

PAT authentication

After you have configured your environment, if you want to use PAT authentication, run the sail set pat command. You can then provide your PAT client ID and client secret. The CLI shows a * for each character you type or paste, so you can see that your input was received.

Once you have provided your client ID and client secret, you can swap your auth method to PAT using sail set auth pat.

If the tenant rejects your PAT client ID or client secret, the CLI tells you which environment failed. The PAT may be wrong, deleted, or created in a different tenant. Run sail set pat to update the credentials. If you use environment variables, check the values of SAIL_CLIENT_ID and SAIL_CLIENT_SECRET.

Troubleshooting configuration

If the CLI cannot find a usable environment, it stops and tells you how to fix the problem:

Error	Fix
no environment is configured	Run sail env create to set up an environment, or set the SAIL_BASE_URL, SAIL_CLIENT_ID, and SAIL_CLIENT_SECRET environment variables.
no active environment is selected or the active environment "{name}" does not exist	The CLI lists your configured environments. Run sail env use {name} to select one, or sail env create to add a new one.
configured environment is missing BaseURL or missing TenantURL	Run sail env update {environment} to set the URLs.
no PAT client ID is stored for environment "{name}" or no PAT client secret is stored ...	Run sail set pat to store your PAT credentials, or set SAIL_CLIENT_ID and SAIL_CLIENT_SECRET.
invalid authtype configured	Run sail set auth to choose oauth or pat.

Environment variable configuration

You can also store your configuration in environment variables. This can be useful when you are using the CLI in an automated environment like a continuous integration and continuous deployment (CI/CD) pipeline. In these types of scenarios, consuming the configuration from environment variables would be easier than creating the configuration file.

When SAIL_BASE_URL is set, the CLI does not need a configured environment, so you do not have to run sail env create.

To export the environment variables on Linux/Mac, open your terminal app and run these commands:

export SAIL_BASE_URL=https://{tenant}.api.identitynow.com
export SAIL_CLIENT_ID={clientID}
export SAIL_CLIENT_SECRET={clientSecret}

To get your environment variables to persist across terminal sessions, add these exports to your shell profile, something like ~/.bash_profile.

To store your configuration in environment variables on Windows, run Powershell as an administrator and run these commands:

$env:SAIL_BASE_URL='https://{tenant}.api.identitynow.com'
$env:SAIL_CLIENT_ID='{clientID}'
$env:SAIL_CLIENT_SECRET='{clientSecret}'

To get your environment variables to persist across PowerShell sessions, run this command instead:

[System.Environment]::SetEnvironmentVariable('SAIL_BASE_URL','https://{tenant}.api.identitynow.com')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_ID','{clientID}')
[System.Environment]::SetEnvironmentVariable('SAIL_CLIENT_SECRET','{clientSecret}')

Usage

Run the sail command for an overview of available commands and flags. You can use the -h flag with any command to see additional options for each command:

These commands are available:

• connectors: This command is a CLI interface for the SaaS Connectivity platform. The CLI is the best way to create and manage SaaS connectors within your tenant. For more information about the connectors command, refer to the CLI Connectors guide.
• search: Run this command to access SHF search functionality within the CLI. For more information about the search command, refer to the CLI Search guide.
• set: Run this command to configure your CLI settings. For more information about the set command, refer to the CLI Set guide.
• spconfig: Run this command to access SHF SP Config functionality. For more information about the spconfig command, refer to the CLI SPConfig guide.
• transform: This command is a CLI interface that makes it easy to create, manage, and test transforms. For more information about the transform command, refer to the CLI Transforms guide.
• va: Run this command to access VAs connected to your tenant. For more information about the va command, refer to the CLI VA guide.
• cluster: Run this command to access VA clusters connected to your tenant. For more information about the cluster command, refer to the CLI Clusters guide.
• workflow: Run this command to create and manage workflows within the CLI. For more information about the workflow command, refer to the CLI Workflows guide.

Support

You will find the SailPoint GitHub CLI repo here: https://github.com/sailpoint-oss/sailpoint-cli

Please use GitHub issues to submit bugs or make feature requests.

Contribution

Do you have an idea to help improve the CLI? You can contribute directly!

Before you contribute, you must sign our CLA and read the Contribution Guidelines.

Questions

If you have questions about the CLI, don't hesitate to reach out on the SailPoint Developer Community forum at https://developer.sailpoint.com/discuss!