Idsec CLI Golang

The official command-line interface for Idira Identity Security Platform operations

Installation

Homebrew

Install the CLI with Homebrew:

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

Go

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.

Docker

Multi-arch images (linux/amd64 and linux/arm64) are published to Docker Hub at cyberark/idsec-cli-golang. Each release pushes a multi-arch manifest list and moves the per-arch tags to the new build:

Tag	What it resolves to
<version>	Multi-arch manifest list pinned to that release — Docker auto-selects the matching arch
latest	Multi-arch manifest list pointing at the most recent release
amd64	Single-platform linux/amd64 image of the most recent build
arm64	Single-platform linux/arm64 image of the most recent build

Pin a specific version for reproducible installs — Docker picks the right architecture automatically:

docker pull cyberark/idsec-cli-golang:<version>   # e.g. 1.2.3

If you need to force a specific architecture (for example, running the amd64 image under emulation on Apple Silicon, or pulling for an air-gapped target host), use either --platform or the per-arch tag (note: the per-arch tags always track the latest build, not a specific version):

docker pull --platform linux/amd64 cyberark/idsec-cli-golang:<version>
# or pull the per-arch tag directly (always the latest build)
docker pull cyberark/idsec-cli-golang:arm64

The image's ENTRYPOINT is idsec and its working directory is /data, so files in the directory you launch from are reachable as ./<filename>. Mount ~/.idsec to persist profiles and the keyring between runs:

docker run --rm -it \
  -v "$(pwd):/data" \
  -v "$HOME/.idsec:/idsec" \
  cyberark/idsec-cli-golang:<version> \
  configure

Mounting the whole /idsec path matters: the cached credentials are encrypted under key material the image keeps beside them, under /idsec/keys, and a cache that outlives the key protecting it cannot be read, so mounting only part of the path means logging in again on every run.

CLI Usage

Both the SDK and the CLI works with profiles

The profiles can be configured upon need and be used for the consecutive actions

The CLI has the following basic commands:

• configure - Configures profiles and their respective authentication methods
• login - Logs into the profile authentication methods
• status - Shows whether a profile is authenticated and how much time is left before its token expires
• exec - Executes different commands based on the supported services (this is the default command, so it can be omitted)
• profiles - Manage multiple profiles on the machine
• cache - Manage the cache of the authentication methods
• upgrade - Upgrade the CLI to the latest version
• version - Print the Idsec CLI version

configure

The configure command is used to create a profile to work on
The profile consists of infomration regarding which authentication methods to use and what are their method settings, along with other related information such as MFA

How to run:

idsec configure

The profiles are saved to ~/.idsec/profiles

No arguments are required, and interactive questions will be asked

If you wish to only supply arguments in a silent fashion, --silent can be added along with the arugments

Usage:

Configure the CLI

Usage:
  idsec configure [flags]

Flags:
      --allow-output                                    Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification                       Disables certificate verification on HTTPS calls, unsafe!
  -h, --help                                            help for configure
      --isp-auth-method string                          Authentication method for Identity Security Platform (default "default")
      --isp-identity-application string                 Identity Application
      --isp-identity-authorization-application string   Service User Authorization Application
      --isp-identity-mfa-interactive                    Allow Interactive MFA
      --isp-identity-mfa-method string                  MFA Method to use by default [pf, sms, email, otp]
      --isp-identity-tenant-subdomain string            Identity Tenant Subdomain
      --isp-identity-url string                         Identity Url
      --isp-username string                             Username
      --log-level string                                Log level to use while verbose (default "INFO")
      --logger-style string                             Which verbose logger style to use (default "default")
      --profile-description string                      Profile Description
      --profile-name string                             The name of the profile to use
      --pvwa-login-method string                        PVWA Login Method [cyberark, ldap, windows]
      --pvwa-url string                                 PVWA Base URL
      --pvwa-username string                            Username
      --raw                                             Whether to raw output
      --silent                                          Silent execution, no interactiveness
      --trusted-cert string                             Certificate to use for HTTPS calls
      --verbose                                         Whether to verbose log
      --work-with-isp                                   Whether to work with Identity Security Platform services
      --work-with-pvwa                                  Whether to work with Password Vault Web Access services

login

The login command is used to login to the authentication methods configured for the profile

You will be asked to write a password for each respective authentication method that supports password, and alongside that, any needed MFA prompt

Once the login is done, the access tokens are stored on the computer keystore for their lifetime

Once they are expired, a consecutive login will be required

How to run:

idsec login

Usage:

Login to the system

Usage:
  idsec login [flags]

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe!
      --force                       Whether to force login even though token has not expired yet
  -h, --help                        help for login
      --isp-secret string           Secret to authenticate with to Identity Security Platform
      --isp-username string         Username to authenticate with to Identity Security Platform
      --pvwa-secret string          Secret to authenticate with to Password Vault Web Access
      --pvwa-username string        Username to authenticate with to Password Vault Web Access
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
      --no-shared-secrets           Do not share secrets between different authenticators with the same username
      --profile-name string         Profile name to load (default "idsec")
      --raw                         Whether to raw output
      --refresh-auth                If a cache exists, will also try to refresh it
      --show-tokens                 Print out tokens as well if not silent
      --silent                      Silent execution, no interactiveness
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log

Notes:

• You may disable certificate validation for login to different authenticators using the --disable-certificate-verification or supply a certificate to be used, not recommended to disable

status

The status command shows the authentication state of a profile

For each configured authenticator it reports whether you are authenticated, the authenticated username and endpoint, when the cached token expires, and how much time is left before it expires

The information is read from local state only (the profile and the cached token in the keyring), so it never triggers a login or a network request, making it safe to run in scripts and CI

How to run:

idsec status

Usage:

Show the authentication status of a profile

Usage:
  idsec status [flags]

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe!
  -h, --help                        help for status
      --json                        Output the status as JSON
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
      --profile-name string         Profile name to show status for, if not given, uses the current one (default "idsec")
      --raw                         Whether to raw output
      --silent                      Silent execution, no interactiveness
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log

For machine-readable output, use --json:

idsec status --json

exec

The exec command is used to execute various commands based on supported services for the fitting logged in authenticators

exec is the default command, so it can be omitted (e.g. idsec sia sso short-lived-password is equivalent to idsec exec sia sso short-lived-password)

The following services and commands are supported:

• sia - Secure Infrastructure Access Services
  • sso - SIA SSO Management
  • k8s - SIA K8S Management
  • db - SIA DB Management
  • workspaces-db - SIA DB Workspaces Management
  • workspaces-target-sets - SIA VM Target Sets Management
  • secrets-db - SIA DB Secrets Management
  • secrets-vm - SIA VM Secrets Management
  • access - SIA Access Management
  • ssh-ca - SIA SSH Ca Key Management
  • settings - SIA Settings Management
  • certificates - SIA Certificates Management
• cmgr - Connector Manager
• pcloud - PCloud Service
  • accounts - PCloud Accounts Management
  • safes - PCloud Safes Management
  • applications - PCloud Applications Management
• identity - Identity Service
  • directories - Identity Directories Management
  • roles - Identity Roles Management
  • users - Identity Users Management
  • auth-profiles - Identity Auth Profiles Management
  • policies - Identity Policies Management
• policy - Access Control Policies Services
  • cloud-access - secure cloud access policies management
  • db - databases access policies management
  • vm - virtual machines access policies management
• sca - Secure Cloud Access just-in-time elevation
  • cloud-access - Elevate into AWS, Azure, or GCP workspaces with a role
  • group-access - Request just-in-time membership in Microsoft Entra ID groups (Azure only)
  • k8s - Just-in-time access to Kubernetes clusters (EKS and AKS)

Any command has its own subcommands, with respective arguments

For example, generating a short lived password for DB

idsec sia sso short-lived-password

Or a short lived password for RDP

idsec sia sso short-lived-password --service DPA-RDP

Add SIA VM Target Set

idsec sia workspaces-target-sets create --name mydomain.com --type Domain

Add SIA VM Secret

idsec sia secrets-vm create --secret-type ProvisionerUser --provisioner-username=myuser --provisioner-password=mypassword

List connector pools

idsec cmgr pools list

Get connector installation script

idsec sia access connector-setup-script --connector-type ON-PREMISE --connector-os windows --connector-pool-id 588741d5-e059-479d-b4c4-3d821a87f012

Create a PCloud Safe

idsec pcloud safes create --safe-name=safe

Create a PCloud Account

idsec pcloud accounts create --name account --safe-name safe --platform-id='UnixSSH' --username root --address 1.2.3.4 --secret-type=password --secret mypass

Retrieve a PCloud Account Credentials

idsec pcloud accounts get-credentials --account-id 11_1

Create an Identity User

idsec identity users create --roles "DpaAdmin" --username "myuser"

Create an Identity service / oauth user

idsec identity users create-user --roles "DpaAdmin" --username "myuser" --is-service-user --is-oauth-client

Configure User Attributes Schema

idsec identity users upsert-attributes-schema --columns '[{"name": "department_attr1", "Title": "department_attr1", "Type": "Text", "Description": "Department attribute 1"}, {"name": "location_attr2", "Title": "location_attr2", "Type": "Text", "Description": "Location attribute 2"}]'

Remove User Attributes Schema Columns

idsec identity users delete-attributes-schema --column-names department_attr1,location_attr2

Get User Attributes Schema

idsec identity users attributes-schema

Set User Attributes

idsec identity users upsert-attributes --user-id 692d75bf-a7a5-4abe-8e37-7056d3337beb --attributes department_attr1:engineering --attributes location_attr2:NYC

Remove User Attributes

idsec identity users delete-attributes --user-id 692d75bf-a7a5-4abe-8e37-7056d3337beb --attribute-names department_attr1,location_attr2

Get User Attributes

idsec identity users get-attributes --user-id 692d75bf-a7a5-4abe-8e37-7056d3337beb

Create an Identity Role

idsec identity roles create-role --role-name myrole

List all directories identities

idsec identity directories list-entities

Add SIA Database Strong Account

idsec sia db-strong-accounts create --store-type managed --name "my-postgres-account" --platform PostgreSQL --address "db.example.com" --username "dbuser" --port 5432 --database "mydb" --password "mypassword"

Delete SIA Database Secret

idsec sia secrets-db delete --secret-name mysecret

Add SIA database

idsec sia workspaces-db create --name mydatabase --provider-engine aurora-mysql --read-write-endpoint myrds.com

Delete SIA database

idsec sia workspaces-db delete --id databaseid

List all SIA Settings

idsec sia settings list-settings

Get specific SIA setting

idsec sia settings adb-mfa-caching

Set specific SIA setting

idsec sia settings set-rdp-mfa-caching --is-mfa-caching-enabled=true --client-ip-enforced=false

Get Secrets Hub Configuration

idsec sechub configurations get

Update Secrets Hub Configuration

idsec sechub configurations update --sync-settings 360

Get Secrets Hub Filters

idsec sechub filters get --store-id store-e488dd22-a59c-418c-bbe3-3f061dd9b667

Add Secrets Hub Filter

idsec sechub filters create --type "PAM_SAFE" --store-id store-e488dd22-a59c-418c-bbe3-3f061dd9b667 --data-safe-name "example-safe"

Delete Secrets Hub Filter

idsec sechub filters delete --filter-id filter-7f3d187d-7439-407f-b968-ec27650be692 --store-id store-e488dd22-a59c-418c-bbe3-3f061dd9b667

Get Secrets Hub Scans

idsec sechub scans get

Trigger Secrets Hub Scan

idsec sechub scans trigger --id default --secret-stores-ids store-e488dd22-a59c-418c-bbe3-3f061dd9b667 type secret-store

Create Secrets Hub Secret Store

idsec sechub secret-stores create --type AWS_ASM --description sdk-testing --name "SDK Testing" --state ENABLED --data-aws-account-alias ALIAS-NAME-EXAMPLE --data-aws-region-id us-east-1 --data-aws-account-id 123456789123 --data-aws-rolename Secrets-Hub-IAM-Role-Name-Created-For-Secrets-Hub

Retrieve Secrets Hub Secret Store

idsec sechub secret-stores get --secret-store-id store-e488dd22-a59c-418c-bbe3-3f061dd9b667

Update Secrets Hub Secret Store

idsec sechub secret-stores update --secret-store-id store-7f3d187d-7439-407f-b968-ec27650be692 --name "New Name" --description "Updated Description" --data-aws-account-alias "Test2"

Delete Secrets Hub Secret Store

idsec sechub secret-stores delete --secret-store-id store-fd11bc7c-22d0-4d9b-ac1b-f8458161935f

Get Secrets Hub Secrets

idsec sechub secrets get-secrets

Get Secrets Hub Secrets using a filter

idsec sechub secrets get-secrets-by --limit 5 --projection EXTEND --filter "name CONTAINS EXAMPLE"

Get Secrets Hub Service Information

idsec sechub service-info get

List Secrets Hub Sync Policies

idsec sechub sync-policies list

Get Secrets Hub Sync Policy

idsec sechub sync-policies get --policy-id policy-7f3d187d-7439-407f-b968-ec27650be692 --projection EXTEND

Create Secrets Hub Sync Policy

idsec sechub sync-policies create --name "New Sync Policy" --description "New Sync Policy Description" --filter-type PAM_SAFE --filter-data-safe-name EXAMPLE-SAFE-NAME --source-id store-e488dd22-a59c-418c-bbe3-3f061dd12367 --target-id store-e488dd22-a59c-418c-bbe3-3f061dd9b667

Delete Secrets Hub Sync Policy

idsec sechub sync-policies delete --policy-id policy-7f3d187d-7439-407f-b968-ec27650be692

List Sessions

idsec sm sessions list

Count Sessions

idsec sm sessions count

List Sessions By Filter

idsec sm sessions list-by --search "duration LE 01:00:00"

Count Sessions By Filter

idsec sm sessions count-by --search "command STARTSWITH ls"

Get Session

idsec sm sessions get --session-id my-id

Get Sessions Statistics

idsec sm sessions stats

List Session Activities

idsec sm session-activities list --session-id my-id

Count Session Activities

idsec sm session-activities count --session-id my-id

List Session Activities By Filter

idsec sm session-activities list-by --session-id my-id --command-contains "ls"

Count Session Activities By Filter

idsec sm session-activities count-by --session-id my-id --command-contains "chmod"

List all policies

idsec policy list-policies

Delete DB Policy

idsec policy db delete-policy --policy-id my-policy-id

List DB Policies

idsec policy db list-policies

Get DB Policy

idsec policy db policy --policy-id my-policy-id

Create DB Policy

idsec policy db create-policy --request-file /path/to/policy-request.json

List Cloud Access Policies

idsec policy cloud-access list-policies

Get Cloud Access Policy

idsec policy cloud-access policy --policy-id my-policy-id

Create Cloud Access Policy

idsec policy cloud-access create-policy --request-file /path/to/policy-request.json

Delete Cloud Access Policy

idsec policy cloud-access delete-policy --policy-id my-policy-id

List VM Policies

idsec policy vm list-policies

Get VM Policy

idsec policy vm policy --policy-id my-policy-id

Delete VM Policy

idsec policy vm delete-policy --policy-id my-policy-id

Connect to MySQL ZSP with the mysql cli via Idsec CLI

idsec sia db mysql --target-address myaddress.com

Connect to PostgreSQL Vaulted with the psql cli via Idsec CLI

idsec sia db psql --target-address myaddress.com --target-user myuser

Generate a connection string alias for a given raw connection string

idsec sia shortened-connection-string generate --raw-connection-string=jack.sparrow@caribbean.airlines#caribbean-airlines@the.black.pearl.com103639

Install SIA SSH public key on a target machine

idsec sia ssh-ca install-public-key --private-key-path /path/to/key.pem --target-machine 1.1.1.1 --username user

Remove SIA SSH public key from a target machine

idsec sia ssh-ca uninstall-public-key --private-key-path /path/to/key.pem --target-machine 1.1.1.1 --username user

Check if SIA SSH public key is installed on a target machine

idsec sia ssh-ca is-public-key-installed --private-key-path /path/to/key.pem --target-machine 1.1.1.1 --username user

Add a SIA certificate

idsec sia certificates create --cert-name name --cert-type PEM --file /path/to/cert.crt

Update a SIA certificate

idsec sia certificates update --certificate-id cert-id --cert-name new-name --file /path/to/new-cert.crt

List all SIA certificates

idsec sia certificates list

Import a pCloud Platform

idsec pcloud platforms import --platform-zip-path /path/to/zip

Import a pCloud Target Platform

idsec pcloud target-platforms import --platform-zip-path /path/to/zip

Export a pCloud Platform

idsec pcloud platforms export --platform-id myid --output-folder /path/to/folder

Export a pCloud Target Platform

idsec pcloud target-platforms export --target-platform-id 123 --output-folder /path/to/folder

List pCloud Target Platforms

idsec pcloud target-platforms list

Activate a pCloud Target Platform

idsec pcloud target-platforms activate --target-platform-id 123

Deactivate a pCloud Target Platform

idsec pcloud target-platforms deactivate --target-platform-id 123

Delete a pCloud Target Platform

idsec pcloud target-platforms delete --target-platform-id 123

Create an Identity Auth Profile

idsec identity auth-profiles create-auth-profile --auth-profile-name myprofile --first-challenges UP --second-challenges EMAIL,OTP

List Identity Auth Profiles

idsec identity auth-profiles list-auth-profiles

Delete an Identity Auth Profile

idsec identity auth-profiles delete-auth-profile --auth-profile-id ab75c8da-b04b-4c6e-9b6e-165e36c24018

Create an Identity Policy

idsec identity policies create-policy --policy-name mypolicy --auth-profile-name "myprofile"

List Identity Policies

idsec identity policies list-policies

Make an Identity Policy Inactive

idsec identity policies update-policy --policy-name mypolicy --policy-status Inactive

Delete an Identity Policy

idsec identity policies delete-policy --policy-name mypolicy

Create a pCloud Application

idsec pcloud applications create --app-id myapp --business-owner-f-name "user" --business-owner-l-name "name" --business-owner-email user@name.com

List pCloud Applications

idsec pcloud applications list

Delete pCloud Application

idsec pcloud applications delete --app-id myapp

Create a pCloud Application Auth Method

idsec pcloud applications create-auth-method --app-id myapp --auth-type hash --auth-value myhash --comment mycomment

Delete a pCloud Application Auth Method

idsec pcloud applications delete-auth-method --app-id myapp --auth-id 1

List SCA cloud-access targets across all providers

idsec sca cloud-access list-targets

List SCA cloud-access targets for a single provider

idsec sca cloud-access list-targets --csp aws

Elevate into a single AWS account (omit --organization-id)

idsec sca cloud-access elevate --csp aws --workspace-id 123456789012 --role-ids arn:aws:iam::123456789012:role/SCA-ReadOnly

Elevate into an AWS account managed by an AWS organization

idsec sca cloud-access elevate --csp aws --workspace-id 210987654321 --organization-id o-a1b2c3d4e5 --role-ids arn:aws:iam::210987654321:role/SCA-PowerUser

Elevate into an Azure resource scope (subscription, resource group, resource, or management group)

idsec sca cloud-access elevate --csp azure --workspace-id subscriptions/5a1c8e77-2b93-41d0-8f6e-c94b2d7a1e05 --organization-id 3c9f7b2e-51d4-4a86-9f0c-7e15d8a4b632 --role-ids /subscriptions/5a1c8e77-2b93-41d0-8f6e-c94b2d7a1e05/providers/Microsoft.Authorization/roleDefinitions/3498e952-d568-435e-9b2c-8d77e338d7f7

Elevate into an Azure resource scope with multiple roles (up to 5 per call)

idsec sca cloud-access elevate --csp azure --workspace-id subscriptions/5a1c8e77-2b93-41d0-8f6e-c94b2d7a1e05 --organization-id 3c9f7b2e-51d4-4a86-9f0c-7e15d8a4b632 --role-ids /subscriptions/5a1c8e77-2b93-41d0-8f6e-c94b2d7a1e05/providers/Microsoft.Authorization/roleDefinitions/3498e952-d568-435e-9b2c-8d77e338d7f7,/subscriptions/5a1c8e77-2b93-41d0-8f6e-c94b2d7a1e05/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7

Elevate into a Microsoft Entra ID directory role (bare-GUID role ID, directory ID for both --workspace-id and --organization-id)

idsec sca cloud-access elevate --csp azure --workspace-id 3c9f7b2e-51d4-4a86-9f0c-7e15d8a4b632 --organization-id 3c9f7b2e-51d4-4a86-9f0c-7e15d8a4b632 --role-ids fe930be7-5e62-47db-91af-98c3a49a38b1

Elevate into a GCP project, folder, or organization (organization ID always required; up to 5 roles per call)

idsec sca cloud-access elevate --csp gcp --workspace-id acme-prod-payments-458213 --organization-id 884271936502 --role-ids roles/iam.securityReviewer

List SCA group-access targets (Azure only)

idsec sca group-access list-targets --csp azure

Elevate into one or more Microsoft Entra ID groups (up to 5 per call)

idsec sca group-access elevate --csp azure --directory-id 3c9f7b2e-51d4-4a86-9f0c-7e15d8a4b632 --groups 9d3b6f41-8c27-4e59-b1a0-5f7e2c84d913,1f8c5a20-4b76-49e3-9d82-6c015be7f4a9

For the full SCA workflow — reading list-targets output, per-provider flows, partial-success handling, and elevation limits — see docs/howto/sca_native_cli.md.

List only Amazon Elastic Kubernetes Service (EKS) clusters

idsec sca k8s list-targets --csp aws

List only Azure Kubernetes Service (AKS) clusters

idsec sca k8s list-targets --csp azure

List all cloud-managed Kubernetes clusters (EKS, AKS)

idsec sca k8s list-targets

Generate kubeconfig for Amazon Elastic Kubernetes Service (EKS) only

idsec sca k8s generate-kubeconfig --csp aws

Generate kubeconfig for Azure Kubernetes Service only

idsec sca k8s generate-kubeconfig --csp azure

Generate kubeconfig for all cloud-managed Kubernetes services (default — writes ~/.kube/idsec-cli/aws.yaml and ~/.kube/idsec-cli/azure.yaml)

idsec sca k8s generate-kubeconfig

Run kubectl commands using the generated kubeconfig

export KUBECONFIG=~/.kube/config:~/.kube/idsec-cli/aws.yaml:~/.kube/idsec-cli/azure.yaml
kubectl get pods
kubectl get nodes

For more information about working with cloud-managed Kubernetes, see Commands for cloud-managed Kubernetes.

Use --help to view all commands for each action

Notes:

• You may disable certificate validation for login to different authenticators using the --disable-certificate-verification or supply a certificate to be used, not recommended to disable

Useful Env Vars:

• IDSEC_PROFILE - Sets the profile to be used across the CLI
• IDSEC_DISABLE_CERTIFICATE_VERIFICATION - Disables certificate verification on REST API's

query

The query command runs a jq expression against JSON produced by an idsec command — read from a file (for example output saved with --output-path) or from standard input. The expression is evaluated in-process using gojq, so the jq binary does not need to be installed.

This is the standalone counterpart to the inline --query flag available on exec, login, profiles list, and configure: instead of querying a command's live output, query filters JSON you already have — from a saved file or piped in.

How to run:

# Save a command's output, then query it later
idsec exec cmgr pools list --output-path pools.json
idsec query --path pools.json --query '.[] | select(.type == "ACCESS") | .name'

# Or pipe JSON in without ever writing it to disk
idsec exec cmgr pools list | idsec query --query '.[] | select(.type == "ACCESS") | .name'

Usage:

Run a jq query on JSON produced by an idsec command (from a file or stdin)

Usage:
  idsec query [flags]

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --arg stringArray             Bind a jq variable to a string value, as name=value (usable as $name); repeatable
      --argjson stringArray         Bind a jq variable to a JSON value, as name=json (usable as $name); repeatable
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe!
  -h, --help                        help for query
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
  -n, --null-input                  Do not read any input; run the query against null (like jq -n)
      --path string                 Path to a JSON file produced by an idsec command; use '-' or omit to read JSON from stdin
      --query string                jq expression to evaluate against the JSON content
      --raw                         Raw output: disable colored output; with --query, also print string results unquoted (like jq -r)
      --silent                      Silent execution, no interactiveness
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log

Bind shell values to jq variables with --arg name=value / --argjson name=json (referenced as $name) instead of interpolating them into the query string, which avoids jq-program injection when the value is user-supplied. As in jq, the environment is reachable via env / $ENV — a safer channel than argv for secrets. See docs/commands/query.md for the full reference.

profiles

As one may have multiple environments to manage, this would also imply that multiple profiles are required, either for multiple users in the same environment or multiple tenants

Therefore, the profiles command manages those profiles as a convenient set of methods

Using the profiles as simply running commands under:

idsec profiles

Usage:

Manage profiles

Usage:
  idsec profiles [command]

Available Commands:
  add         Add a profile from a given path
  clear       Clear all profiles
  clone       Clone a profile
  delete      Delete a specific profile
  edit        Edit a profile interactively
  list        List all profiles
  show        Show a profile

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe!
      --disable-telemetry           Disables telemetry data collection
  -h, --help                        help for profiles
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
      --raw                         Whether to raw output
      --silent                      Silent execution, no interactiveness
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log

Use "idsec profiles [command] --help" for more information about a command.

cache

Use the cache command to manage the Idsec data cached on your machine. Currently, you can only clear the filesystem cache (not data cached in the OS's keystore).

Using the cache as simply running commands under:

idsec cache

Usage:

Manage cache

Usage:
  idsec cache [command]

Available Commands:
  clear       Clears all profiles cache

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe!
  -h, --help                        help for cache
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
      --raw                         Whether to raw output
      --silent                      Silent execution, no interactiveness
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log

Use "idsec cache [command] --help" for more information about a command.

upgrade

Use the upgrade command to upgrade to the latest idsec version or check what is the latest.

Using the upgrade as simply running:

idsec upgrade

Usage:

Manage upgrades

Usage:
  idsec upgrade [flags]

Flags:
      --allow-output                Allow stdout / stderr even when silent and not interactive
      --disable-cert-verification   Disables certificate verification on HTTPS calls, unsafe! Avoid using in production environments!
      --dry-run                     Whether to dry run
  -h, --help                        help for upgrade
      --log-level string            Log level to use while verbose (default "INFO")
      --logger-style string         Which verbose logger style to use (default "default")
      --raw                         Whether to raw output
      --silent                      Silent execution, no interactiveness
      --suppress-version-check      Whether to suppress version check
      --trusted-cert string         Certificate to use for HTTPS calls
      --verbose                     Whether to verbose log
      --version string              Version to upgrade to (default: latest)

version

Use the version command to print the Idsec CLI version and build metadata embedded into the binary at build time.

Run:

idsec version

The default output prints a multi-line block of build metadata, for example:

Idsec v0.3.1
Build Number: 3
Build Date: 2026-05-20T13:31:52Z
Git Commit: 8e682dc6b01ac408b1e66f0162809bd877a496cc
Git Branch: main

When the running binary is older than the latest published GitHub release, a yellow upgrade hint is appended below the metadata block, matching the wording used by the other CLI commands that run the same check, e.g.:

A newer version of idsec is available. Run `idsec upgrade` to upgrade to version 0.4.0.

The hint is best-effort: the GitHub release check is bounded by a 5-second timeout and is silently omitted on any failure (no network, GitHub unreachable, rate-limited, slow/hung response, etc.). It also honors the IDSEC_SUPPRESS_UPGRADE_CHECK environment variable, so offline or restricted environments see no extra noise. Unlike the incidental nag that other commands print, idsec version runs the check on every invocation (no 12-hour disk cache) so the answer always reflects the current state.

For machine-readable output (raw semantic version, without the Idsec or leading v prefix), suitable for shell scripting:

idsec version --silent

This prints just the bare version on a single line, e.g.:

0.3.1

The upgrade hint is intentionally suppressed in --silent mode so that callers parsing $(idsec version --silent) always receive only the version string.

Configuration File

The CLI supports an optional YAML configuration file that sets default values for environment variables. This is useful for persisting settings across sessions without exporting environment variables in your shell profile.

File Location

The default configuration file path is ~/.idsec/config.yaml. You can override this with:

1. The --config flag (highest priority)
2. The IDSEC_CONFIG_FILE environment variable
3. The default path ~/.idsec/config.yaml

# Use a custom config file for a single command
idsec --config /path/to/my-config.yaml login

# Or set the env var once in your shell profile
export IDSEC_CONFIG_FILE=/path/to/my-config.yaml

File Format

Keys are the full IDSEC_* environment variable names. Any key that does not start with IDSEC_ is ignored with a warning.

# ~/.idsec/config.yaml

# Logging
IDSEC_FILE_LOG_PATH: /var/log/idsec/cli.log
IDSEC_FILE_LOG_LEVEL: DEBUG
IDSEC_LOG_LEVEL: INFO

# Profile
IDSEC_PROFILE: myprofile
IDSEC_PROFILES_FOLDER: /custom/profiles

# Security
IDSEC_DISABLE_CERTIFICATE_VERIFICATION: true
IDSEC_EXTRA_TRUSTED_CA_CERTS_BUNDLE_PATH: /path/to/ca-bundle.pem

# Proxy
IDSEC_PROXY_ADDRESS: http://proxy.corp:8080
IDSEC_PROXY_USERNAME: user
IDSEC_PROXY_PASSWORD: secret

# Keyring
IDSEC_BASIC_KEYRING: true
IDSEC_KEYRING_FOLDER: /custom/keyring

# Telemetry
IDSEC_DISABLE_TELEMETRY_COLLECTION: true

# Upgrade
IDSEC_SUPPRESS_UPGRADE_CHECK: true

Precedence

Settings are resolved in the following order (highest priority first):

Priority	Source	Example
1	CLI flags	--verbose, --log-level DEBUG
2	Environment variables	export IDSEC_FILE_LOG_LEVEL=DEBUG
3	Configuration file	IDSEC_FILE_LOG_LEVEL: DEBUG in config.yaml
4	Built-in defaults	INFO for file log level

This means environment variables always override the config file, and CLI flags always override both.

Accepted Keys

Two kinds of keys are accepted:

1. Any key starting with IDSEC_ — exported as the matching environment variable. There is no fixed whitelist; every current and future IDSEC_* variable consumed by the CLI or SDK can be set from the file.
2. Standard proxy variables — HTTP_PROXY, HTTPS_PROXY, NO_PROXY and their lowercase forms (http_proxy, https_proxy, no_proxy). These are honored directly by Go's net/http package.

Any other key is ignored with a warning.

For a list of IDSEC_* variables actually read by the CLI and SDK, run idsec --help or refer to the SDK documentation. Common examples:

IDSEC_PROFILE: myprofile
IDSEC_FILE_LOG_LEVEL: DEBUG
IDSEC_PROXY_ADDRESS: http://proxy.corp:8080
IDSEC_DISABLE_TELEMETRY_COLLECTION: true

HTTPS_PROXY: http://proxy.corp:8080
NO_PROXY: localhost,127.0.0.1

Security Note

If your configuration file contains sensitive values (e.g., IDSEC_PROXY_PASSWORD), ensure the file has restrictive permissions:

chmod 600 ~/.idsec/config.yaml

File Logging

The CLI automatically writes log output to a file on disk, independent of stdout logging. This provides a persistent record of CLI operations for debugging and auditing.

Default Behavior

File logging is enabled by default when using the CLI. No configuration is needed.

Setting	Default
Log file path	~/.idsec/logs/idsec-cli.log
Log level	INFO
Max file size	50 MB
Backup history	5 rotated files
File permissions	0600 (owner read/write only)
Directory permissions	0700 (owner only)

Environment Variables

Both settings can be overridden via environment variables:

Variable	Description	Default
IDSEC_FILE_LOG_PATH	Path to the log file.	~/.idsec/logs/idsec-cli.log
IDSEC_FILE_LOG_LEVEL	Minimum level to write to file (DEBUG, INFO, WARNING, ERROR, CRITICAL). Set to none or off to disable file logging.	INFO

Example -- disable file logging:

export IDSEC_FILE_LOG_LEVEL=off

Example -- write DEBUG-level logs to a custom path:

export IDSEC_FILE_LOG_PATH=/var/log/idsec/cli.log
export IDSEC_FILE_LOG_LEVEL=DEBUG
idsec login --profile-name myprofile

Independence from Stdout

File logging and stdout logging are fully independent:

• Stdout is controlled by --verbose, --log-level, and IDSEC_LOG_LEVEL. Without --verbose, stdout is silent.
• File is controlled by IDSEC_FILE_LOG_PATH and IDSEC_FILE_LOG_LEVEL. It always writes regardless of --verbose.

This means you can keep stdout silent while still capturing detailed logs to the file:

# No --verbose: stdout is silent, but file still captures INFO+ logs
idsec pcloud safes list
cat ~/.idsec/logs/idsec-cli.log

Credential Sanitization

Sensitive values are automatically redacted in file logs. Fields such as password, secret, token, private_key, authorization, and AWS credential fields are replaced with [REDACTED] before being written to disk. Stdout output is not sanitized.

Log Rotation

When the log file exceeds 50 MB, it is rotated automatically:

~/.idsec/logs/idsec-cli.log      (current)
~/.idsec/logs/idsec-cli.log.1    (previous)
~/.idsec/logs/idsec-cli.log.2
~/.idsec/logs/idsec-cli.log.3
~/.idsec/logs/idsec-cli.log.4
~/.idsec/logs/idsec-cli.log.5    (oldest, removed on next rotation)

Development Guidelines

CLI Command Structure

To maintain a consistent and predictable user experience across the Idsec CLI, all commands must adhere to the following structural and naming conventions.

Command Hierarchy

The command hierarchy is strictly defined as Service → Resource → Action.

Syntax:

idsec <service> <resource> <action> [flags/parameters]

Definitions:

• Service: The high-level product or domain (e.g., pcloud, cmgr, sia).
• Resource: The specific entity being manipulated (e.g., safes, networks, pools). Plural nouns are preferred for resources.
• Action: The operation to perform on the resource (e.g., create, list, delete).

Resource & Action Separation

Do not repeat the resource name inside the action name. The context is provided by the resource command that precedes it.

Examples:

• ❌ Bad: idsec pcloud safes create-safe (Redundant)
• ✅ Good: idsec pcloud safes create (Clean)

Standard Actions & Verbs

To prevent confusion (e.g., users guessing between "remove", "delete", or "destroy"), use the following standard verbs for common CRUD operations:

Intent	Canonical Verb	Accepted Aliases	Description
Create	create	add	Creates a new resource.
Read Many	list	ls	Returns a list of resources. Should support filtering.
Read One	get	read	Returns details of a specific resource. Usually requires an ID or name.
Update	update	edit	Modifies an existing resource.
Delete	delete	rm	Permanently removes a resource.

Command Examples

Creating a Safe:

# Correct
idsec pcloud safes create --safe-name="MySafe"

# Incorrect (Redundant naming)
idsec pcloud safes create-safe --safe-name="MySafe"

Listing connector pools:

# Correct
idsec cmgr pools list

# Incorrect (Wrong hierarchy)
idsec cmgr list-pools

Adding an Action to an Existing Resource

This guide walks through adding a new action to a resource that already exists (e.g., adding get-credentials to pcloud/accounts). The process involves changes in both the SDK (idsec-sdk-golang) and the CLI (idsec-cli-golang) repositories.

Architecture Overview

The CLI uses a reflection-based execution model. When a user runs:

idsec pcloud accounts get-credentials --account-id 11_1

The CLI resolves this as a method chain via reflection:

api.Pcloud() → .Accounts() → .GetCredentials(input)

The action name get-credentials is converted to the method name GetCredentials (hyphens removed, TitleCase). The --account-id flag is parsed from the model struct's flag tag and populated into the input struct.

Here is how the pieces fit together across both repos:

idsec-sdk-golang                              idsec-cli-golang
├── pkg/services/<svc>/<res>/                 ├── pkg/services/<svc>/<res>/
│   ├── models/                               │   └── actions/
│   │   └── request/response structs          │       └── *_cli_actions.go
│   ├── actions/                              │           (imports ActionToSchemaMap from SDK)
│   │   └── *_actions_schemas.go              │
│   │       (maps action names → model structs)│
│   ├── *_service.go                          │
│   │   └── API methods (Create, Get, etc.)   │
│   └── *_service_config.go                   │
│       └── service registration              │

The SDK owns the models, the service methods, and the ActionToSchemaMap that maps action names to model structs. The CLI imports ActionToSchemaMap from the SDK, so schema definitions are maintained in a single place.

Key files you will touch:

File	Repo	Purpose
pkg/services/<svc>/<res>/models/*.go	SDK	Model struct defining the action's input parameters
pkg/services/<svc>/<res>/*_service.go	SDK	Method implementing the API call
pkg/services/<svc>/<res>/actions/*_actions_schemas.go	SDK	Maps the action name to the model struct (shared by CLI and Terraform)

Step 1: Define the Model in the SDK

Create a model struct for the action's input parameters in the SDK's models/ directory for the resource.

File naming convention: idsec_<service>_<action_description>.go

// idsec-sdk-golang/pkg/services/pcloud/accounts/models/idsec_pcloud_get_account_credentials.go
package models

type IdsecPCloudGetAccountCredentials struct {
    AccountID string `json:"account_id,omitempty" mapstructure:"account_id" desc:"The account ID" flag:"account-id" validate:"required"`
    Reason    string `json:"reason,omitempty" mapstructure:"reason,omitempty" desc:"Reason for retrieving credentials" flag:"reason"`
}

Each field uses struct tags that control how it behaves across the system:

Tag	Purpose	Example
json	JSON field name for the API request/response	json:"account_id,omitempty"
mapstructure	Field mapping for internal config parsing	mapstructure:"account_id"
desc	Description shown in CLI --help output	desc:"The account ID"
flag	CLI flag name (always use kebab-case)	flag:"account-id"
validate	Validation rules, checked before execution	validate:"required"
default	Default value applied when flag is not provided	default:"false"

If the action takes no parameters (e.g., a simple list), skip this step — you'll use nil in the schema map.

You may also need a response model if the action returns data that needs to be structured (e.g., IdsecPCloudAccountCredentials). Response models typically only need json tags.

Step 2: Implement the Method in the SDK

Add the method to the existing service file. The method name must match the CLI action name converted to TitleCase with hyphens removed:

CLI action name	SDK method name
get-credentials	GetCredentials()
list-by	ListBy()
add-member	AddMember()
create	Create()
stats	Stats()

// idsec-sdk-golang/pkg/services/pcloud/accounts/idsec_pcloud_accounts_service.go

func (s *IdsecPCloudAccountsService) GetCredentials(input *models.IdsecPCloudGetAccountCredentials) (*models.IdsecPCloudAccountCredentials, error) {
    url := fmt.Sprintf("%s/%s/credentials", accountsURL, input.AccountID)
    resp, err := s.client.Get(url, nil)
    if err != nil {
        return nil, err
    }
    var result models.IdsecPCloudAccountCredentials
    err = common.UnmarshalResponse(resp, &result)
    return &result, err
}

Method signature rules:

• The method receiver is on the existing service struct
• Input parameter: pointer to the model struct you defined in Step 1 (or no input for parameterless actions)
• Return: response struct pointer + error

Step 3: Add the Schema Mapping in the SDK

Edit the existing actions_schemas.go in the SDK repo and add a new entry to the ActionToSchemaMap:

// idsec-sdk-golang/pkg/services/pcloud/accounts/actions/idsec_pcloud_accounts_actions_schemas.go

var ActionToSchemaMap = map[string]interface{}{
    "create":          &accountsmodels.IdsecPCloudAddAccount{},
    "get":             &accountsmodels.IdsecPCloudGetAccount{},
    // ... existing actions ...
    "get-credentials": &accountsmodels.IdsecPCloudGetAccountCredentials{},  // add this line
}

Schema mapping rules:

• The key is the action name as it appears in the CLI (kebab-case)
• The value is a pointer to an empty instance of the model struct
• Use nil for actions that take no parameters (e.g., "list": nil)
• The CLI framework automatically generates flags from the struct's flag tags, validates using validate tags, and populates the struct before calling the SDK method
• The ActionToSchemaMap is defined once in the SDK and imported by the CLI via an sdkactions alias

No CLI changes are needed. The action is automatically available because:

1. The resource is already registered in pkg/registry/init.go
2. The CLIAction already references sdkactions.ActionToSchemaMap (imported from the SDK)
3. Adding a new entry to the SDK's map is all it takes to expose a new action in the CLI

Step 4: Build and Verify

# In the CLI repo, update the SDK dependency to pick up the new action
go get github.com/cyberark/idsec-sdk-golang@<branch-or-commit>
go mod tidy

# Build the CLI
make all

# Check the new action appears in help
idsec pcloud accounts --help

# Inspect the generated flags
idsec pcloud accounts get-credentials --help

# Test the action
idsec pcloud accounts get-credentials --account-id 11_1

Summary

Adding an action to an existing resource is a 3-file change, all in the SDK:

1. SDK — model struct (models/idsec_<svc>_<action>.go)
2. SDK — service method (*_service.go)
3. SDK — one line in ActionToSchemaMap (actions/*_actions_schemas.go)

No changes to the CLI repo are required. The CLI imports ActionToSchemaMap from the SDK, so new actions are picked up automatically after updating the SDK dependency.

Enable Attribute

The Enable attribute controls whether services and actions are available in the CLI. Use it to hide work-in-progress features from releases.

When to Use the Enable Attribute

• New services that are not ready for production
• Experimental actions that need more testing
• Features waiting for approval or documentation

How to Disable an Action

Set Enabled to false in the action definition. The action will be filtered out.

var CLIAction = &actions.IdsecServiceCLIActionDefinition{
    IdsecServiceBaseActionDefinition: actions.IdsecServiceBaseActionDefinition{
        ActionName: "experimental-action",
        Enabled:    boolPtr(false),  // Will be filtered out
    },
}

Build Flag

The Enable attribute filtering is controlled by a build flag. By default, filtering is OFF and all services and actions are available.

Default build (filtering OFF):

go build ./...

Release build (filtering ON):

go build -ldflags "-X github.com/cyberark/idsec-sdk-golang/pkg/services.releasedFeaturesOnly=true" ./...

When filtering is ON, services and actions with Enabled: false are excluded.

Best Practices

1. Default is enabled. Omit the field or set it to nil for normal behavior.
2. Remove the attribute when the feature is ready. Do not leave disabled attributes in production code.
3. The Enable attribute is checked at startup. It cannot be changed at runtime.
4. Use the build flag to enable filtering for release builds.

License

This project is licensed under Apache License 2.0 - see LICENSE for more details

Copyright (c) 2026 CyberArk Software Ltd. All rights reserved.