cyberark/idsec-cli-golang repository overview

⁠Idsec CLI

The Idsec CLI is a Go command-line tool to interact with CyberArk Identity Security services (profile management, PCloud account operations, service execution, and more).

Full documentation is published at cyberark.github.io/idsec-cli-golang⁠.

⁠Tags

There are two sets of supported tags:

• latest — the most recently released version of the Idsec CLI. There are no backwards-compatibility guarantees when relying on latest. See notes on backwards compatibility⁠ for more information.
• <major.minor.patch> — each released version of the Idsec CLI (e.g. 1.2.3). These tags are immutable; they are only ever pushed once, on release.

⁠Docker CLI usage

The Idsec CLI can be executed from the Docker CLI with the docker run command:

$ docker run --rm -it cyberark/idsec-cli-golang:1.2.3 version

This prints the version of the Idsec CLI being used in the container. Note that the idsec executable is not specified on the docker run line because it is defined as the image's entrypoint.

For any Idsec CLI command, you can request help with --help:

$ docker run --rm -it cyberark/idsec-cli-golang:1.2.3 --help
$ docker run --rm -it cyberark/idsec-cli-golang:1.2.3 configure --help

For the full command reference, see the Idsec CLI documentation site⁠.

⁠Persist profiles and the keyring across runs

The Idsec CLI stores profiles at /idsec/profiles and the credential keyring at /idsec/keyring inside the container (controlled by the IDSEC_PROFILES_FOLDER and IDSEC_KEYRING_FOLDER environment variables). Without a volume mount, both are lost when the container exits. Mount ~/.idsec from the host to persist them between runs:

$ docker run --rm -it \
    -v "$HOME/.idsec:/idsec" \
    cyberark/idsec-cli-golang:1.2.3 \
    configure

⁠Read and write host files

The image's working directory is /data — the user-facing scratch area for input/output. Mount your current host directory there so the CLI can read inputs and write outputs to it:

$ docker run --rm -it \
    -v "$HOME/.idsec:/idsec" \
    -v "$(pwd):/data" \
    cyberark/idsec-cli-golang:1.2.3 \
    <subcommand> --input ./input.json

Anything you write under /data inside the container shows up in your current working directory on the host.

⁠Convenience alias

To shorten docker commands, add a shell alias:

$ alias idsec='docker run --rm -it -v "$HOME/.idsec:/idsec" -v "$(pwd):/data" cyberark/idsec-cli-golang:latest'

You can then invoke the CLI as if it were installed natively on the host:

$ idsec version
$ idsec configure

⁠Notes on interfaces and backwards compatibility of Docker image

• The only tool supported on this image is the Idsec CLI. Only the idsec executable should ever be invoked directly.
• The /data directory is user-controlled. The image will not write to it unless an Idsec CLI command does so on your behalf.
• The container runs as a non-root user (idsec-cli). Files written into bind-mounted host volumes will be owned by that user's in-container UID. If you need files in ~/.idsec or your working directory to be owned by your host user, run the container with --user "$(id -u):$(id -g)" and pre-create the host directories with appropriate permissions.
• IDSEC_PROFILES_FOLDER defaults to /idsec/profiles, IDSEC_KEYRING_FOLDER defaults to /idsec/keyring. Mounting /idsec (or each subdirectory individually) is what persists CLI state across runs.
• There are no backwards-compatibility guarantees when relying on the latest tag. Between updates to latest, any of the following may change:
  • The base image (currently alpine:3.19) may be upgraded.
  • Default environment variable values, working directory, or the non-root user UID may change.
  • A new major version of the Idsec CLI may be published.
• To guarantee backwards compatibility, pin to a specific <major.minor.patch> tag — those are immutable; they will only ever be pushed to once upon release of a particular version of the Idsec CLI.

⁠General Idsec CLI usage

For information on general usage of the Idsec CLI, please refer to:

• The Idsec CLI documentation site⁠ — full command reference, guides, and configuration details.
• The project README⁠ — quick start and repository overview.

⁠Source code

The source for the Idsec CLI lives at github.com/cyberark/idsec-cli-golang⁠. The Docker image is built from docker/Dockerfile⁠ in that repository.

⁠Feedback

To file feature requests or report issues related to this Docker image, please open an issue at the GitHub repository⁠.