### Install yaml-crypt Locally

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Install the package locally within a project for project-specific usage.

```bash
$ mkdir yaml-crypt && cd yaml-crypt
$ yarn init --yes
$ yarn add yaml-crypt
$ ./node_modules/.bin/yaml-crypt -h
```

--------------------------------

### Install yaml-crypt Globally

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Install the package globally using yarn to use the command-line utility directly.

```bash
$ yarn global add yaml-crypt
$ yaml-crypt -h
```

--------------------------------

### Generate and Write Keys to Config File

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Generate a new key and write it to the config file interactively. The key can then be used by name.

```bash
# Write a new key to the config file interactively from stdin
yaml-crypt --generate-key | yaml-crypt --write-key my-new-key

# Then use it by name
yaml-crypt -k c:my-new-key secrets.yaml
```

--------------------------------

### CLI Key Source Specifiers

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

The -k / -K flags accept prefixes to load keys from various sources like config files, environment variables, or file descriptors.

```bash
# From a key file (default when no prefix)
yaml-crypt -k ./my-key-file secrets.yaml

# From the config file by name
yaml-crypt -k c:production-key secrets.yaml

# From an environment variable
yaml-crypt -k e:YAML_CRYPT_KEY secrets.yaml

# From file descriptor 0 (stdin), piped from a secrets manager
vault kv get -field=key secret/yaml-crypt | yaml-crypt -k fd:0 secrets.yaml

# Explicit encryption key with multiple decryption keys (key rotation scenario)
yaml-crypt -k c:old-key -k c:new-key -K c:new-key secrets.yaml-crypt
```

--------------------------------

### Configuration file — `~/.yaml-crypt/config.yaml`

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Keys stored in the configuration file are automatically picked up by the CLI and by `loadFile()` / `loadConfig()`. Binary keys can be stored as base64 using the YAML `!!binary` tag.

```APIDOC
## Configuration File (`~/.yaml-crypt/config.yaml`)

### Description
Store keys in `~/.yaml-crypt/config.yaml` for automatic loading by the CLI and library functions. Supports binary keys via `!!binary` tag.

### Example Configuration
```yaml
# ~/.yaml-crypt/config.yaml
keys:
  - name: production
    key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4'
  - name: staging
    key: 'c2Vjb25ka2V5MTIzNDU2Nzg5MGFiY2Rl'
  - name: binary-key
    key: !!binary dGhpcyBpcyBhIDMyLWJ5dGUga2V5ISE=
```

### Usage
```bash
# Write a new key to the config file interactively from stdin
yaml-crypt --generate-key | yaml-crypt --write-key my-new-key

# Then use it by name
yaml-crypt -k c:my-new-key secrets.yaml
```
```

--------------------------------

### loadFile(path, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Asynchronously loads and decrypts a YAML file from the specified path. It uses keys from the default configuration file or a provided configuration object. Supports loading multi-document files.

```APIDOC
## loadFile(path, opts?)

### Description
Async helper that reads a YAML file from disk, decrypts it using keys from the user's `~/.yaml-crypt/config.yaml` (or a supplied config object), and returns the parsed JavaScript object. Pass `{ loadAll: true }` for multi-document files.

### Method
`loadFile(path, opts?)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { loadFile, loadConfig } = require('yaml-crypt');

// Using keys from ~/.yaml-crypt/config.yaml automatically
async function readSecret() {
  try {
    const obj = await loadFile('./secrets.yaml-crypt');
    console.log('DB password:', obj.data.db_pass);
  } catch (e) {
    console.error('Failed to load file:', e.message);
  }
}

// Supplying an explicit config (bypasses disk lookup)
async function readSecretExplicit() {
  const config = { keys: [{ key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'k1' }] };
  const obj = await loadFile('./secrets.yaml-crypt', { config });
  console.log(obj);
}

// Multi-document file
async function readMulti() {
  const docs = await loadFile('./multi.yaml-crypt', { loadAll: true });
  docs.forEach(d => console.log(d));
}

readSecret();
```

### Response
#### Success Response
- `object`: The decrypted JavaScript object representing the YAML content.
- `array`: If `opts.loadAll` is true, an array of decrypted JavaScript objects for multi-document files.
```

--------------------------------

### generateKey(algorithm?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Generates a cryptographically random 32-byte key suitable for Fernet or Branca encryption. Returns the key as a base64 string.

```APIDOC
## generateKey(algorithm?)

### Description
Generates a cryptographically random 32-byte key suitable for use with either the Fernet or Branca algorithm. Returns the key as a base64 string.

### Parameters
#### Path Parameters
- **algorithm** (string) - Optional - Specifies the encryption algorithm ('fernet' or 'branca'). Defaults to 'fernet'.

### Request Example
```javascript
const { generateKey } = require('yaml-crypt');

// Generate a Fernet key (default)
const fernetKey = generateKey('fernet');
console.log(fernetKey); // e.g. "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4"

// Generate a Branca key
const brancaKey = generateKey('branca');
console.log(brancaKey); // e.g. "MTIzNDU2Nzg5MGFiY2RlZmdoaWprbG1u"
```

### CLI Equivalent
```bash
$ yaml-crypt --generate-key > my-key-file
$ yaml-crypt --generate-key -a branca > my-branca-key
```
```

--------------------------------

### loadConfig(opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Asynchronously loads the yaml-crypt configuration file, typically located at `~/.yaml-crypt/config.yaml`. This function is useful for programmatically accessing stored keys.

```APIDOC
## loadConfig(opts?)

### Description
Async function that reads `~/.yaml-crypt/config.yaml` (or `config.yml`) and returns the parsed configuration object. Useful when you want to reuse the user's stored keys programmatically.

### Method
`loadConfig(opts?)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { loadConfig, yamlcrypt } = require('yaml-crypt');

async function setup() {
  // Load from default location: ~/.yaml-crypt/config.yaml
  const config = await loadConfig();

  // Override the home directory (useful in tests)
  const testConfig = await loadConfig({ home: '/tmp/test-home' });

  // Load from an explicit path
  const customConfig = await loadConfig({ path: '/etc/myapp/yaml-crypt.yaml' });

  const crypt = yamlcrypt(config);
  const obj = crypt.decrypt(encryptedYaml);
  console.log(obj);
}

setup();
```

### Response
#### Success Response
- `object`: The parsed configuration object for yaml-crypt.
```

--------------------------------

### CLI — Key source specifiers

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

The `-k` / `-K` flags accept several prefixes to load keys from different sources, enabling secrets to come from config files, environment variables, file descriptors, or key files.

```APIDOC
## CLI Key Source Specifiers

### Description
Use prefixes with `-k` or `-K` flags to specify key sources like config files, environment variables, or file descriptors.

### Usage
```bash
# From a key file (default when no prefix)
yaml-crypt -k ./my-key-file secrets.yaml

# From the config file by name
yaml-crypt -k c:production-key secrets.yaml

# From an environment variable
yaml-crypt -k e:YAML_CRYPT_KEY secrets.yaml

# From file descriptor 0 (stdin)
vault kv get -field=key secret/yaml-crypt | yaml-crypt -k fd:0 secrets.yaml

# Explicit encryption key with multiple decryption keys
yaml-crypt -k c:old-key -k c:new-key -K c:new-key secrets.yaml-crypt
```
```

--------------------------------

### Configure Default Keys in config.yaml

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Specify default encryption keys in `~/.yaml-crypt/config.yaml` to avoid providing them on the command line for every operation.

```yaml
keys:
- key: my-raw-key-data
- key: !!binary my-base64-key-data
```

```bash
$ yaml-crypt my-file.yaml
```

--------------------------------

### Configuration File for Keys

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Keys stored in `~/.yaml-crypt/config.yaml` are automatically used by the CLI and `loadFile()` / `loadConfig()`. Binary keys can be stored using the `!!binary` tag.

```yaml
# ~/.yaml-crypt/config.yaml
keys:
  - name: production
    key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4'
  - name: staging
    key: 'c2Vjb25ka2V5MTIzNDU2Nzg5MGFiY2Rl'
  - name: binary-key
    key: !!binary dGhpcyBpcyBhIDMyLWJ5dGUga2V5ISE=
```

--------------------------------

### Load YamlCrypt configuration file

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Asynchronously loads the yaml-crypt configuration file from default or specified paths. Useful for programmatically accessing stored user keys.

```javascript
const { loadConfig, yamlcrypt } = require('yaml-crypt');

async function setup() {
  // Load from default location: ~/.yaml-crypt/config.yaml
  const config = await loadConfig();

  // Override the home directory (useful in tests)
  const testConfig = await loadConfig({ home: '/tmp/test-home' });

  // Load from an explicit path
  const customConfig = await loadConfig({ path: '/etc/myapp/yaml-crypt.yaml' });

  const crypt = yamlcrypt(config);
  const obj = crypt.decrypt(encryptedYaml);
  console.log(obj);
}

setup();
```

--------------------------------

### Encrypt with Base64 for Kubernetes Secrets

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

When encrypting data intended for Kubernetes secrets, use the --base64 (or -B) option to ensure proper encoding.

```bash
$ yaml-crypt -B -k my-key-file my-file.yaml
```

--------------------------------

### Load and decrypt a YAML file with YamlCrypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Asynchronously loads and decrypts a YAML file. Uses keys from default config or a provided config object. Supports multi-document files with `loadAll: true`.

```javascript
const { loadFile, loadConfig } = require('yaml-crypt');

// Using keys from ~/.yaml-crypt/config.yaml automatically
async function readSecret() {
  try {
    const obj = await loadFile('./secrets.yaml-crypt');
    console.log('DB password:', obj.data.db_pass);
  } catch (e) {
    console.error('Failed to load file:', e.message);
  }
}

// Supplying an explicit config (bypasses disk lookup)
async function readSecretExplicit() {
  const config = { keys: [{ key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'k1' }] };
  const obj = await loadFile('./secrets.yaml-crypt', { config });
  console.log(obj);
}

// Multi-document file
async function readMulti() {
  const docs = await loadFile('./multi.yaml-crypt', { loadAll: true });
  docs.forEach(d => console.log(d));
}

readSecret();
```

--------------------------------

### Create yaml-crypt Instance

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Initializes a Yamlcrypt instance with decryption keys and an optional explicit encryption key. Supports single keys, key objects, or arrays of keys.

```javascript
const { yamlcrypt } = require('yaml-crypt');

const crypt = yamlcrypt({
  keys: [
    { key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'primary' },
    { key: 'c2Vjb25ka2V5MTIzNDU2Nzg5MGFiY2Rl', name: 'old-key' }  // for decryption only
  ],
  encryptionKey: { key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'primary' }
});
```

--------------------------------

### Encrypt and Decrypt Raw Strings with Fernet and Branca

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Use these functions for direct token-level encryption and decryption without YAML parsing. Ensure the correct algorithm and key are provided. The output is a Fernet (base64url) or Branca (base62) token string.

```javascript
const { encrypt, decrypt, generateKey } = require('yaml-crypt');

const key = generateKey('fernet'); // 32-byte base64 key

// Encrypt a raw string
const token = encrypt('fernet:0x80', key, 'top secret payload');
console.log(token); // "gAAAAAB..."

// Decrypt it back
const plain = decrypt('fernet:0x80', key, token);
console.log(plain); // "top secret payload"

// Same with Branca (base62-encoded token)
const brancaKey = generateKey('branca');
const brancaToken = encrypt('branca:0xBA', brancaKey, 'another secret');
const brancaPlain = decrypt('branca:0xBA', brancaKey, brancaToken);
console.log(brancaPlain); // "another secret"

// CLI equivalent
// $ echo "top secret payload" | yaml-crypt -k my-key-file --raw --encrypt
// $ echo "gAAAAAB..." | yaml-crypt -k my-key-file --raw --decrypt
```

--------------------------------

### Yamlcrypt.encrypt(str, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Encrypts a YAML document by parsing the string, walking string leaf values, wrapping them in !yaml-crypt tags, and serializing the result back to YAML.

```APIDOC
## Yamlcrypt.encrypt(str, opts?)

### Description
Parses the YAML string, walks all string leaf values (or only those under `opts.path`), wraps them in `!yaml-crypt` tags, and serializes the result back to a YAML string with the values replaced by ciphertext.

### Parameters
#### Path Parameters
- **str** (string) - Required - The YAML document string to encrypt.
- **opts** (object) - Optional - Configuration options for encryption.
  - **opts.path** (string) - Optional - A specific path to encrypt (e.g., 'data.password'). If not provided, all string values are encrypted.
  - **opts.algorithm** (string) - Optional - The encryption algorithm to use ('fernet' or 'branca'). Defaults to 'fernet'.
  - **opts.raw** (boolean) - Optional - If true, encrypts the input string directly without parsing it as YAML.

### Request Example
```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const plainYaml = `
apiVersion: v1
kind: Secret
data:
  username: admin
  password: s3cr3t
`.trim();

// Encrypt all string values
const encrypted = crypt.encrypt(plainYaml);
console.log(encrypted);
// apiVersion: v1
// kind: Secret
// data:
//   username: !<!yaml-crypt> gAAAAAB...
//   password: !<!yaml-crypt> gAAAAAB...

// Encrypt only values under 'data.password'
const partial = crypt.encrypt(plainYaml, { path: 'data.password' });

// Use Branca instead of Fernet
const branca = crypt.encrypt(plainYaml, { algorithm: 'branca' });

// Encrypt raw string (not YAML)
const rawToken = crypt.encrypt('my secret value', { raw: true });
```
```

--------------------------------

### CLI — Transparent editor mode (`--edit` / `-E`)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Opens the decrypted YAML in `$EDITOR`. On save and exit, only modified values are re-encrypted; unchanged ciphertext is preserved verbatim.

```APIDOC
## CLI Transparent Editor Mode (`--edit` / `-E`)

### Description
Opens the decrypted YAML in your default editor (`$EDITOR`). Modified values are re-encrypted upon saving, while unchanged ciphertext remains intact.

### Usage
```bash
# Open an encrypted file for editing
yaml-crypt -E -k my-key-file secrets.yaml-crypt

# Use a specific editor
EDITOR=nano yaml-crypt -E -k my-key-file secrets.yaml-crypt

# Inside the editor, mark new values with the !yaml-crypt tag to have them encrypted on save:
# data:
#   existing_key: !<!yaml-crypt/:0> (already decrypted, re-encrypted on save)
#   new_key: !<!yaml-crypt> my-new-plaintext-value
```
```

--------------------------------

### Low-level crypto primitives: encrypt/decrypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Direct token-level encryption and decryption without any YAML parsing. `encrypt` returns a Fernet (base64url) or Branca (base62) token string. `decrypt` reverses it.

```APIDOC
## encrypt(algorithm, key, msg) / decrypt(algorithm, key, msg)

### Description
Direct token-level encryption and decryption without any YAML parsing. `encrypt` returns a Fernet (base64url) or Branca (base62) token string. `decrypt` reverses it.

### Parameters
#### encrypt
- **algorithm** (string) - Required - The encryption algorithm (e.g., 'fernet', 'branca').
- **key** (string) - Required - The encryption key.
- **msg** (string) - Required - The message to encrypt.

#### decrypt
- **algorithm** (string) - Required - The encryption algorithm (e.g., 'fernet', 'branca').
- **key** (string) - Required - The decryption key.
- **token** (string) - Required - The token to decrypt.

### Request Example (encrypt)
```javascript
const { encrypt } = require('yaml-crypt');
const key = generateKey('fernet'); // Assuming generateKey is available
const token = encrypt('fernet:0x80', key, 'top secret payload');
```

### Response Example (encrypt)
```
"gAAAAAB..."
```

### Request Example (decrypt)
```javascript
const { decrypt } = require('yaml-crypt');
const key = '...'; // Your key
const token = 'gAAAAAB...'; // Encrypted token
const plain = decrypt('fernet:0x80', key, token);
```

### Response Example (decrypt)
```
"top secret payload"
```
```

--------------------------------

### Encrypt YAML File

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Encrypt all values within a YAML file using a specified key file. The encrypted file will be saved with a '-crypt' suffix.

```bash
$ yaml-crypt -k my-key-file my-file.yaml
```

--------------------------------

### Generate Encryption Key with yaml-crypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Generates a base64 encoded 32-byte key for Fernet or Branca encryption. The CLI equivalent is `yaml-crypt --generate-key`.

```javascript
const { generateKey } = require('yaml-crypt');

// Generate a Fernet key (default)
const fernetKey = generateKey('fernet');
console.log(fernetKey); // e.g. "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4"

// Generate a Branca key
const brancaKey = generateKey('branca');
console.log(brancaKey); // e.g. "MTIzNDU2Nzg5MGFiY2RlZ2doaWprbG1u"

// CLI equivalent
// $ yaml-crypt --generate-key > my-key-file
// $ yaml-crypt --generate-key -a branca > my-branca-key
```

--------------------------------

### CLI File and Directory Processing

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

The CLI automatically determines operation (encrypt/decrypt) from file extension. Directories can be traversed with -D (shallow) or -R (recursive). Options like --keep, --force, --path, and -B are available.

```bash
# Encrypt a single file (renames to secrets.yaml-crypt)
yaml-crypt -k my-key-file secrets.yaml

# Decrypt a single file (renames to secrets.yaml)
yaml-crypt -k my-key-file secrets.yaml-crypt

# Keep the original file after encryption
yaml-crypt -k my-key-file --keep secrets.yaml

# Force overwrite of existing output file
yaml-crypt -k my-key-file --force secrets.yaml

# Encrypt all YAML files in a directory (non-recursive)
yaml-crypt -k my-key-file -D ./config/

# Encrypt all YAML files recursively, continuing on errors
yaml-crypt -k my-key-file -R --continue ./project/

# Encrypt only specific paths within the document
yaml-crypt -k my-key-file --path data secrets.yaml

# Kubernetes Secret: encrypt Base64-encoded values
yaml-crypt -k my-key-file -B --path data k8s-secret.yaml
```

--------------------------------

### CLI — File and directory processing

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

The CLI determines the operation (encrypt vs. decrypt) automatically from the file extension. Directories can be traversed with `-D` (shallow) or `-R` (recursive).

```APIDOC
## CLI File and Directory Processing

### Description
Automatically determines encryption or decryption based on file extension. Supports directory traversal for batch processing.

### Usage
```bash
# Encrypt a single file (renames to secrets.yaml-crypt)
yaml-crypt -k my-key-file secrets.yaml

# Decrypt a single file (renames to secrets.yaml)
yaml-crypt -k my-key-file secrets.yaml-crypt

# Keep the original file after encryption
yaml-crypt -k my-key-file --keep secrets.yaml

# Force overwrite of existing output file
yaml-crypt -k my-key-file --force secrets.yaml

# Encrypt all YAML files in a directory (non-recursive)
yaml-crypt -k my-key-file -D ./config/

# Encrypt all YAML files recursively, continuing on errors
yaml-crypt -k my-key-file -R --continue ./project/

# Encrypt only specific paths within the document
yaml-crypt -k my-key-file --path data secrets.yaml

# Kubernetes Secret: encrypt Base64-encoded values
yaml-crypt -k my-key-file -B --path data k8s-secret.yaml
```
```

--------------------------------

### yamlcrypt(opts)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Factory function that returns a Yamlcrypt instance configured with decryption keys and an optional explicit encryption key.

```APIDOC
## yamlcrypt(opts)

### Description
Factory function that returns a `Yamlcrypt` instance configured with decryption keys and an optional explicit encryption key. `opts.keys` accepts a single key string, a key object `{ key, name }`, or an array of either. When only one key is supplied it is used for both encryption and decryption.

### Parameters
#### Request Body
- **opts** (object) - Required - Configuration options for the Yamlcrypt instance.
  - **opts.keys** (string | object | Array<string | object>) - Required - Decryption keys. Can be a single key string, an object `{ key, name }`, or an array of these.
  - **opts.encryptionKey** (object) - Optional - The key to use for encryption. If not provided, the first key in `opts.keys` is used.
    - **opts.encryptionKey.key** (string) - Required - The encryption key.
    - **opts.encryptionKey.name** (string) - Required - The name of the encryption key.

### Request Example
```javascript
const { yamlcrypt } = require('yaml-crypt');

const crypt = yamlcrypt({
  keys: [
    { key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'primary' },
    { key: 'c2Vjb25ka2V5MTIzNDU2Nzg5MGFiY2Rl', name: 'old-key' }  // for decryption only
  ],
  encryptionKey: { key: 'YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4', name: 'primary' }
});
```
```

--------------------------------

### Generate Encryption Key

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Generate a new random encryption key and save it to a file. This key is required for encrypting and decrypting YAML documents.

```bash
$ yaml-crypt --generate-key > my-key-file
```

--------------------------------

### CLI Transparent Editor Mode

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Opens encrypted YAML in `$EDITOR` for editing. On save, only modified values are re-encrypted, preserving unchanged ciphertext. Use !yaml-crypt tag for new values.

```bash
# Open an encrypted file for editing
yaml-crypt -E -k my-key-file secrets.yaml-crypt

# Use a specific editor
EDITOR=nano yaml-crypt -E -k my-key-file secrets.yaml-crypt

# Inside the editor, mark new values with the !yaml-crypt tag to have them encrypted on save:
# data:
#   existing_key: !<!yaml-crypt/:0> (already decrypted, re-encrypted on save)
#   new_key: !<!yaml-crypt> my-new-plaintext-value
```

--------------------------------

### Decrypt YAML File

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Decrypt a '.yaml-crypt' file using the corresponding key file. The operation is inferred from the file extension.

```bash
$ yaml-crypt -k my-key-file my-file.yaml-crypt
```

--------------------------------

### Yamlcrypt.encryptAll(str, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Encrypts all documents within a multi-document YAML stream. It functions similarly to encrypt() but handles streams separated by '---'.

```APIDOC
## Yamlcrypt.encryptAll(str, opts?)

### Description
Same as `encrypt()` but handles YAML files containing multiple documents separated by `---`.

### Parameters
#### Path Parameters
- **str** (string) - Required - The multi-document YAML stream string to encrypt.
- **opts** (object) - Optional - Configuration options for encryption. See `encrypt()` for available options.

### Request Example
```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const multiDoc = `
apiVersion: v1
kind: ConfigMap
data:
  db_host: localhost
---
apiVersion: v1
kind: Secret
data:
  db_pass: hunter2
`.trim();

const encrypted = crypt.encryptAll(multiDoc);
// Both documents are encrypted; separator "---" is preserved.
console.log(encrypted);
```

### CLI Equivalent
```bash
$ yaml-crypt -k my-key-file -e < multi.yaml
```
```

--------------------------------

### Explicitly Encrypt or Decrypt YAML File

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Use the -e or -d flags to explicitly specify encryption or decryption operations, respectively, when the file extension might be ambiguous.

```bash
$ yaml-crypt -e -k my-key-file my-file.yaml
$ yaml-crypt -d -k my-key-file my-file.yaml-crypt
```

--------------------------------

### isToken(data) — Detect whether a value is an encrypted token

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Inspects the leading bytes of a string or Buffer to determine whether it is a Fernet (`0x80`) or Branca (`0xBA`) token without attempting full decryption.

```APIDOC
## isToken(data)

### Description
Inspects the leading bytes of a string or Buffer to determine whether it is a Fernet (`0x80`) or Branca (`0xBA`) token without attempting full decryption.

### Parameters
- **data** (string | Buffer) - Required - The data to inspect.

### Request Example
```javascript
const { isToken } = require('yaml-crypt');
console.log(isToken('gAAAAABl...')); // true
console.log(isToken('0A1B2C...')); // true
console.log(isToken('hello world')); // false
```

### Response Example
```
true | false
```
```

--------------------------------

### Yamlcrypt.transform(str, callback, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Transforms encrypted YAML content in-place. It decrypts the content, passes it to a provided callback function for modification, and then re-encrypts the result. Unmodified ciphertext is preserved.

```APIDOC
## Yamlcrypt.transform(str, callback, opts?)

### Description
Decrypts the YAML content to a plaintext string, passes it to `callback` for arbitrary transformation (add/edit/remove values), then re-encrypts the result using the same key that was used for decryption (or a new key if `opts.encryptionKey` differs). Values that were not modified retain their original ciphertext unchanged. This is the building block for the `--edit` CLI mode.

### Method
`transform(str, callback, opts?)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');
const fs = require('fs');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const encryptedYaml = fs.readFileSync('secrets.yaml-crypt', 'utf8');

const updated = crypt.transform(encryptedYaml, (plaintext, usedKey) => {
  // plaintext is the fully decrypted YAML string
  // Append a new key-value pair
  return plaintext + '\n  new_secret: my-new-value';
});

fs.writeFileSync('secrets.yaml-crypt', updated);
// Only the new value is newly encrypted; pre-existing ciphertext is preserved.
```

### Response
#### Success Response
- `string`: The transformed and re-encrypted YAML string.
```

--------------------------------

### Add New Encrypted Data in Editor

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

While editing an encrypted file, use the `<!yaml-crypt>` tag to specify new data that should be encrypted.

```yaml
unencrypted:
  hello: world
encrypted:
  key1: !<!yaml-crypt/:0> secret-key-1
  # add the following line to add a new encrypted entry "key2" to the file,
  # which will be encrypted in the yaml-crypt file:
  key2: !<!yaml-crypt> secret123
```

--------------------------------

### Detect Encrypted Tokens with isToken

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Inspects the leading bytes of a string or Buffer to determine if it's a Fernet or Branca token. This function does not attempt full decryption.

```javascript
const { isToken } = require('yaml-crypt');

console.log(isToken('gAAAAABl...')); // true  (Fernet token)
console.log(isToken('0A1B2C...')); // true  (Branca token, base62)
console.log(isToken('hello world')); // false (plaintext)
console.log(isToken(Buffer.from('gAAAAABl...'))); // true
```

--------------------------------

### Transform encrypted YAML content in-place with YamlCrypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Decrypts YAML, allows transformation via a callback, and re-encrypts the result. Unmodified ciphertext is preserved.

```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');
const fs = require('fs');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const encryptedYaml = fs.readFileSync('secrets.yaml-crypt', 'utf8');

const updated = crypt.transform(encryptedYaml, (plaintext, usedKey) => {
  // plaintext is the fully decrypted YAML string
  // Append a new key-value pair
  return plaintext + '\n  new_secret: my-new-value';
});

fs.writeFileSync('secrets.yaml-crypt', updated);
// Only the new value is newly encrypted; pre-existing ciphertext is preserved.

// CLI equivalent (opens $EDITOR)
// $ yaml-crypt -E -k my-key-file secrets.yaml-crypt
```

--------------------------------

### Encrypt YAML Document with yaml-crypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Encrypts string values within a YAML document using `!yaml-crypt` tags. Supports full-document, partial-path encryption, and different algorithms. Requires a configured Yamlcrypt instance.

```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const plainYaml = `
apiVersion: v1
kind: Secret
data:
  username: admin
  password: s3cr3t
`.trim();

// Encrypt all string values
const encrypted = crypt.encrypt(plainYaml);
console.log(encrypted);
// apiVersion: v1
// kind: Secret
// data:
//   username: !<!yaml-crypt> gAAAAAB...
//   password: !<!yaml-crypt> gAAAAAB...

// Encrypt only values under 'data.password'
const partial = crypt.encrypt(plainYaml, { path: 'data.password' });

// Use Branca instead of Fernet
const branca = crypt.encrypt(plainYaml, { algorithm: 'branca' });

// Encrypt raw string (not YAML)
const rawToken = crypt.encrypt('my secret value', { raw: true });
```

--------------------------------

### Yamlcrypt.decrypt(str, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Decrypts a YAML string with '!yaml-crypt' tags. It iterates through configured keys to find a match and returns the decrypted JavaScript object. Supports raw decryption of tokens.

```APIDOC
## Yamlcrypt.decrypt(str, opts?)

### Description
Parses the encrypted YAML string (with `!yaml-crypt` tags), decrypts each tagged value by trying each configured key in order, and returns the fully decrypted plain JavaScript object.

### Method
`decrypt(str, opts?)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

// Suppose this was produced by crypt.encrypt(...)
const encryptedYaml = `
apiVersion: v1
kind: Secret
data:
  username: !<!yaml-crypt> gAAAAABl...abc
  password: !<!yaml-crypt> gAAAAABl...xyz
`.trim();

try {
  const obj = crypt.decrypt(encryptedYaml);
  console.log(obj.data.username); // "admin"
  console.log(obj.data.password); // "s3cr3t"
} catch (e) {
  console.error('Decryption failed – no matching key:', e.message);
}

// Decrypt raw token
const rawToken = 'gAAAAABl...';
const plain = crypt.decrypt(rawToken, { raw: true });
console.log(plain); // "my secret value"
```

### Response
#### Success Response
- `object`: The decrypted JavaScript object.
- `string`: If `opts.raw` is true, returns the decrypted string.

#### Response Example
```json
{
  "apiVersion": "v1",
  "kind": "Secret",
  "data": {
    "username": "admin",
    "password": "s3cr3t"
  }
}
```
```

--------------------------------

### Edit Encrypted YAML File

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Open an encrypted YAML file in an editor. The file is decrypted before opening and re-encrypted upon saving.

```bash
$ yaml-crypt -E my-file.yaml-crypt
```

--------------------------------

### Encrypt Specific Path in YAML

Source: https://github.com/autoapply/yaml-crypt/blob/main/README.md

Encrypt only the values at a specified path within a YAML file. This is useful for selectively securing sensitive data.

```yaml
apiVersion: v1
kind: Secret
data:
  username: user1
  password: secret123
```

```bash
$ yaml-crypt --path data -k my-key-file my-file.yaml
```

--------------------------------

### Encrypt Multi-Document YAML Stream with yaml-crypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Encrypts all documents within a multi-document YAML stream, preserving the `---` separator. Use this for files containing multiple YAML documents. The CLI equivalent is `yaml-crypt -k my-key-file -e < multi.yaml`.

```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const multiDoc = `
apiVersion: v1
kind: ConfigMap
data:
  db_host: localhost
---
apiVersion: v1
kind: Secret
data:
  db_pass: hunter2
`.trim();

const encrypted = crypt.encryptAll(multiDoc);
// Both documents are encrypted; separator "---" is preserved.
console.log(encrypted);

// CLI equivalent
// $ yaml-crypt -k my-key-file -e < multi.yaml
```

--------------------------------

### Decrypt a multi-document YAML stream with YamlCrypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Decrypts all documents within a '---' separated YAML stream. An optional callback can be provided to access the key used for decryption.

```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const encryptedMultiDoc = '...'; // produced by encryptAll()

const docs = crypt.decryptAll(encryptedMultiDoc, {
  callback: (usedKey) => console.log('Decrypted with key:', usedKey.source)
});

docs.forEach((doc, i) => {
  console.log(`Document ${i}:`, JSON.stringify(doc, null, 2));
});

// CLI equivalent
// $ yaml-crypt -k my-key-file -d < multi.yaml-crypt
```

--------------------------------

### Yamlcrypt.decryptAll(str, opts?)

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Decrypts all documents within a `---`-separated YAML stream. It returns an array of parsed JavaScript objects. An optional callback can be provided to receive the key object used for decryption.

```APIDOC
## Yamlcrypt.decryptAll(str, opts?)

### Description
Decrypts all documents in a `---`-separated YAML stream and returns an array of parsed objects. Accepts an optional `opts.callback` that receives the key object used for successful decryption.

### Method
`decryptAll(str, opts?)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

const encryptedMultiDoc = '...'; // produced by encryptAll()

const docs = crypt.decryptAll(encryptedMultiDoc, {
  callback: (usedKey) => console.log('Decrypted with key:', usedKey.source)
});

docs.forEach((doc, i) => {
  console.log(`Document ${i}:`, JSON.stringify(doc, null, 2));
});
```

### Response
#### Success Response
- `array`: An array of decrypted JavaScript objects, one for each document in the stream.

#### Response Example
```json
[
  {
    "key1": "value1"
  },
  {
    "key2": "value2"
  }
]
```
```

--------------------------------

### Decrypt a YAML document with YamlCrypt

Source: https://context7.com/autoapply/yaml-crypt/llms.txt

Decrypts an encrypted YAML string using configured keys. Handles potential decryption failures if no key matches. Can also decrypt raw tokens.

```javascript
const { yamlcrypt, generateKey } = require('yaml-crypt');

const key = generateKey();
const crypt = yamlcrypt({ keys: key });

// Suppose this was produced by crypt.encrypt(...)
const encryptedYaml = `
apiVersion: v1
kind: Secret
data:
  username: !<!yaml-crypt> gAAAAABl...abc
  password: !<!yaml-crypt> gAAAAABl...xyz
`.trim();

try {
  const obj = crypt.decrypt(encryptedYaml);
  console.log(obj.data.username); // "admin"
  console.log(obj.data.password); // "s3cr3t"
} catch (e) {
  console.error('Decryption failed – no matching key:', e.message);
}

// Decrypt raw token
const rawToken = 'gAAAAABl...';
const plain = crypt.decrypt(rawToken, { raw: true });
console.log(plain); // "my secret value"

// CLI equivalent
// $ yaml-crypt -k my-key-file secret.yaml-crypt
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.