Skip to content

Getting started

Installation

Homebrew

Install the CLI with Homebrew:

brew tap cyberark/tools
brew trust cyberark/tools
brew install idsec

Go

You can install the CLI via go modules.

macOS / Linux

# Requires Go 1.25+
go install github.com/cyberark/idsec-cli-golang/cmd/idsec@latest

Make sure that the PATH environment variable points to the go binary path, for example:

export PATH=$PATH:$(go env GOPATH)/bin

Windows (PowerShell)

# Requires Go 1.25+ and Git for Windows 2.24+ on PATH
go install github.com/cyberark/idsec-cli-golang/cmd/idsec@latest

The Go installer adds its own bin directory to PATH but not the one go install writes to, so add that as well:

$env:Path += ";$(go env GOPATH)\bin"

This lasts for the current session only. To keep it, add the same directory to PATH under System Properties > Environment Variables.

CLI Usage

The CLI supports profiles, which can be configured as needed and used for consecutive actions.

The CLI has the following basic commands:

  • configure: Configure profiles and their authentication methods (see Configure)
  • login: Log in using the configured profile authentication methods (see Login)
  • status: Show whether a profile is authenticated and how much time is left before its token expires (see Status)
  • exec: Execute commands for supported services (see Exec). You can also skip exec and invoke services directly, e.g. idsec sia sso short-lived-password
  • profiles: Manage multiple profiles on the machine (see Profiles)
  • cache: Manage idsec cache on the machine (see Cache)
  • upgrade: Upgrade the CLI to the latest version (see Upgrade)

Basic flow

  1. Configure a profile (either silently or interactively):

    idsec configure --silent --work-with-isp --isp-username myuser

  2. After the profile is configured, log in:

    idsec login --silent --isp-secret mysecret

  3. Execute actions (such as generating a short-lived SSO password):

    idsec sia sso short-lived-password

    You can also use idsec exec sia sso short-lived-password — both forms are equivalent.

Exit codes

idsec exits with 0 on success and non-zero on failure. Since v0.14.0, this includes idsec exec (and implicit idsec <service> … invocations): a failed action, missing profile, expired login, or failed --dry-run now exits 1. Previously these exited 0.

Output streams

Since v0.14.0, idsec writes only command results to stdout:

  • stdout - results: action output (JSON, tables, text), --dry-run plans, --query results, and help you asked for with --help or idsec help.
  • stderr - everything else: failure messages, warnings (including the "newer version available" notice), retry notices, --verbose logs, and usage errors together with the help shown alongside them.

A failing command leaves stdout empty, so idsec exec ... | jq never receives an error message as input. Failure messages are printed to stderr even with --silent. Warnings and notices still follow --silent and --allow-output.

Before v0.14.0, failure messages and --verbose logs were written to stdout. Scripts that searched stdout for messages such as Failed to... should check the exit code instead, or read stderr (for example with 2>&1).