> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/iagctl/create-secret/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# iagctl create secret

Create a new secret.

The `iagctl create secret` command stores sensitive information in the gateway. The gateway currently uses secrets for private repository SSH keys.

The gateway's secrets manager uses asymmetric encryption and stores only the encrypted value in the database. You must use a unique encryption key file to encrypt and decrypt secrets. If you lose the encryption key file, you can't recover any stored secrets.

For more information, see [Create Gateway secret store](../configure-secret-store).

The `iagctl create secret` command supports two storage modes:

* **Local secrets** — the value is encrypted at rest using a key file you control. Use this mode for SSH keys, PyPI/Ansible Galaxy credentials, and other values managed directly by Itential Gateway.
* **External secret aliases** — the value is never stored locally. Itential Gateway records a reference to a secret in an external provider and fetches the plaintext at execution time. Use `--provider`, `--secret`, and optionally `--key` to create an alias.

For more information, see [External secrets overview](../secrets/external-secrets/overview).

## Syntax

```bash
iagctl create secret <secret-name> [flags]
```

## Set up secret encryption

Before you create local secrets, you need to generate an encryption key file and configure the gateway to use it.

### Generate an encryption key file

Generate a robust, random encryption key. The following method is one option:

```bash
openssl rand -base64 256 > /Users/gatewayuser/.gateway.d/gateway_secret.key
```

For improved security, restrict the file permissions:

```bash
chmod 400 /Users/gatewayuser/.gateway.d/gateway_secret.key
```

### Configure the gateway to use the encryption key file

You can provide the encryption key file location to the gateway in two ways:

* **Command line flag:** Use the `--encryption-file` flag with `iagctl create secret` and `iagctl describe secret`. This approach works well for initial setup.

* **Configuration variable:** For permanent access, set the encryption key file location using the `GATEWAY_SECRETS_ENCRYPT_KEY_FILE` environment variable or your gateway configuration file. The gateway needs permanent access to the encryption key file to run services that require stored secrets.

```ini
  [secrets]
  encrypt_key_file = /Users/gatewayuser/.gateway.d/gateway_secret.key
```

If the key file is lost, local secrets cannot be recovered.

## Examples

### Create a local secret with the encryption file flag

The following example creates a secret called `my-secret` and encrypts the literal text `sensitive data` using the file specified by `--encryption-file`:

```bash
iagctl create secret my-secret \
--value "sensitive data" \
--encryption-file /Users/gatewayuser/.gateway.d/gateway_secret.key
```

### Create a local secret with the encryption file configuration variable

The following example creates a secret called `my-secret` and encrypts the literal text `sensitive data`. This command assumes you've already set the `GATEWAY_SECRETS_ENCRYPT_KEY_FILE` configuration variable:

```bash
iagctl create secret my-secret \
--value "sensitive data"
```

### Create a local secret from a file

The following example creates a secret called `git-key` and encrypts the contents of the file `/Users/gatewayuser/.ssh/gateway_git_rsa` using the `@` prefix syntax. This command assumes you've already set the `GATEWAY_SECRETS_ENCRYPT_KEY_FILE` configuration variable:

```bash
iagctl create secret git-key \
--value @/Users/gatewayuser/.ssh/gateway_git_rsa
```

### Create an external secret alias (Vault)

The following example creates an alias called `iosxr-vault` that retrieves the `iosxrpass` field from the `inv_secrets` secret in the `vault-prod` provider. The value is fetched from Vault at execution time — nothing is stored locally:

```bash
iagctl create secret iosxr-vault \
  --provider vault-prod \
  --secret inv_secrets \
  --key iosxrpass
```

### Create an external secret alias (Vault, full secret as JSON)

Omit `--key` to return the full secret data map as a JSON string at execution time:

```bash
iagctl create secret inv-all \
  --provider vault-prod \
  --secret inv_secrets
```

### Create an external secret alias (CyberArk)

For CyberArk providers, the `--secret` value is `SafeName/ObjectName`:

```bash
iagctl create secret db-password \
  --provider cyberark-prod \
  --secret "ProdSafe/DB_Production_Password"
```

### Create an external secret alias (CyberArk, with field extraction)

When the CyberArk object value is a JSON map, use `--key` to extract a specific field:

```bash
iagctl create secret db-password \
  --provider cyberark-prod \
  --secret "ProdSafe/DB_Production_Password" \
  --key password
```

## Options

```bash
  --description string       A brief description of the secret
  --encryption-file string   The file to use for encrypting the secret. Clients and runners need this file for decryption. (local secrets)
  -h, --help                 Help for secret
  --key string               The field to extract when the secret value is a JSON object (external secret aliases)
  --provider string          The name of a configured secret provider (external secret aliases)
  --secret string            The secret identifier in the external provider (external secret aliases). For Vault, this is the path within the secrets mount. For CyberArk, this is SafeName/ObjectName. For plugin providers, this value is passed directly to the plugin.
  --tag stringArray          Metadata tags to associate with the secret
  --value string             The secret value to encrypt. Prefix with '@' to read from a file. (local secrets)
```

## Options inherited from parent commands

```bash
  --profile string   Specify the client profile to use (case-insensitive, defaults to [client] section)
  --config string    Path to the configuration file
  --raw              Display the result of the command in raw format
  --verbose          Enable verbose output
```