summon

summon

Note: The cyberark.github.io/summon documentation site is no longer maintained. This README is the authoritative source for configuration and usage information.

summon is a command-line tool to make working with secrets easier.

It provides an interface for

• Reading a secrets.yml file
• Fetching secrets from a trusted store
• Exporting secret values to a sub-process environment
• Writing secrets to files in various formats (push-to-file)

Install

Note installing summon alone is not sufficient; you need to also install a provider of your choice before it's ready for use.

Pre-built binaries and packages are available from GitHub releases here.

Using Summon with CyberArk Secrets Manager

Summon ships with a built-in Conjur provider. No separate binary install is needed; it activates automatically when the provider directory has no other binaries, or explicitly when you pass --provider conjur.

Note: If the provider directory contains exactly one binary, Summon uses that binary automatically. If it contains two or more, Summon exits with an error and prompts you to specify one with --provider. The built-in Conjur provider is only used as the automatic fallback when the directory is empty.

Are you using this project with Conjur Open Source? Then we strongly recommend choosing the version of this project to use from the latest Conjur OSS suite release. Conjur maintainers perform additional testing on the suite release versions to ensure compatibility. When possible, upgrade your Conjur version to match the latest suite release; when using integrations, choose the latest suite release that matches your Conjur version. For any questions, please contact us on Discourse.

Quick Start

Define a secrets.yml file:

DB_PASSWORD: !var production/db/password
API_KEY: !var production/api/key

Set the required environment variables and run your command:

export CONJUR_APPLIANCE_URL=https://conjur.example.com
export CONJUR_ACCOUNT=myorg
export CONJUR_AUTHN_LOGIN=host/myapp
export CONJUR_AUTHN_API_KEY=

summon -f secrets.yml env | grep -E 'DB_PASSWORD|API_KEY'

No --provider flag is needed; Summon detects the built-in Conjur provider automatically.

For other authentication methods, see Supported Authentication Methods below.

Supported Authentication Methods

The built-in provider supports the following authentication methods via CONJUR_AUTHN_TYPE:

Configuration

The provider loads configuration from:

• .conjurrc in the home directory, current directory, or the path set in CONJUR_RC
• /etc/conjur.conf on Linux/macOS; C:\Windows\conjur.conf on Windows
• Environment variables (take precedence over file-based config)

Connection

SSL certificate precedence: when both CONJUR_SSL_CERTIFICATE and CONJUR_CERT_FILE are set, CONJUR_SSL_CERTIFICATE (inline PEM) takes precedence over CONJUR_CERT_FILE. Only set one to avoid confusion.

CONJUR_CERT_FILE vs CONJUR_AUTHN_CERT_FILE: CONJUR_CERT_FILE is the Conjur server's TLS certificate used to verify the HTTPS connection. CONJUR_AUTHN_CERT_FILE is the client certificate presented to Conjur during certificate authentication (mTLS). They serve different purposes and can both be set at the same time.

Authentication

Certificate authentication requires an HTTPS appliance URL and is not supported on Conjur Cloud (Idira Secrets Manager, SaaS). Both are rejected at config validation, before any request is sent.

Credential storage

Credential storage

The built-in provider uses conjur-api-go credential caching. Two settings work together:

1. Storage mode — whether the configured backend may write cached credentials.
2. Storage backend — where cached credentials are stored (keyring, file, or none).

Storage mode (read/write policy)

By default, the built-in provider runs in read-only mode: it may read existing cached credentials from the configured backend but does not write new ones to the OS keychain or ~/.netrc. This reduces cross-talk when multiple summon processes run concurrently.

Set the mode with CONJUR_CREDENTIAL_STORAGE_MODE:

export CONJUR_CREDENTIAL_STORAGE_MODE=readwrite

Storage backends

When mode is readwrite, credentials are cached using one of three backends:

Configure the backend in .conjurrc:

credential_storage: keyring
keychain_namespace: service-a

credential_storage: file
netrc_path: /path/to/.netrc

Or via environment variables:

export CONJUR_CREDENTIAL_STORAGE=keyring
export CONJUR_KEYCHAIN_NAMESPACE=service-a

export CONJUR_CREDENTIAL_STORAGE=file
export CONJUR_NETRC_PATH=/path/to/.netrc

Enable credential writes to disk

To restore write caching (for example, a single long-lived host identity that should reuse credentials across invocations):

export CONJUR_CREDENTIAL_STORAGE_MODE=readwrite
export CONJUR_CREDENTIAL_STORAGE=file          # optional; keyring is the default backend
export CONJUR_NETRC_PATH="$HOME/.summon-netrc" # optional; defaults to ~/.netrc

With readonly mode (the default), summon still authenticates using credentials supplied in the environment (CONJUR_AUTHN_API_KEY, CONJUR_AUTHN_TOKEN, and so on) and may read an existing cache, but it will not update keychain or netrc files.

Migration from standalone summon-conjur

If you previously installed summon-conjur as a provider binary in your provider directory and relied on Summon's automatic provider detection (no --provider flag), follow these steps:

1. Remove the summon-conjur binary from your provider directory (typically /usr/local/lib/summon/).
2. Summon will use the built-in Conjur provider automatically.

If the binary cannot be removed (for example, it is managed by a system package manager), pass --provider conjur explicitly to select the built-in provider regardless of what is in the provider directory.

If you were passing --provider conjur explicitly, the flag still works. You can also drop it; the built-in provider is now the default.

Homebrew

brew tap cyberark/tools
brew install summon

Linux (Debian and Red Hat flavors)

deb and rpm files are attached to new releases. These can be installed with dpkg -i summon_v*.deb and rpm -ivh summon_v*.rpm, respectively.

Aut