Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

cottage Configuration Specification

This document describes the specification of cottage.toml and *.cott.toml files used by cottage.

  1. Project Configuration - cottage.toml
    1. Root Fields
    2. UpstreamConfig
    3. PullPushConfig
  2. Secret Metadata - .cott.toml
    1. Root Fields
    2. ChecksumMetadata
    3. PreviewMetadata
    4. SecretMetadata
    5. UpstreamMetadata

Project Configuration - cottage.toml

The cottage.toml file is located at the project root and defines global and upstream settings.

Root Fields

FieldTypeDescription
upstreamMap<String, UpstreamConfig>Optional. Defines upstream configurations for pulling/pushing secrets.

UpstreamConfig

These settings can be defined at the top level of an upstream or within its pull/push sections.

FieldTypeDescription
cwdBooleanOptional. If true, run the script in the directory of the secret.
envfilePathOptional. Path to an encrypted file to use as environment variables for the script.
varsMap<String, String>Optional. Environment variables to pass to the script. If any variable value is a path to a decrypted secret that has a corresponding encrypted counterpart, it is automatically added to the requires list.
requiresArrayOptional. List of secret paths to be decrypted before running push/pull operations (and securely cleaned up afterwards).
shellStringOptional. The shell to use for running scripts (default: sh).
pullPullPushConfigOptional. Specific configuration for the pull operation.
pushPullPushConfigOptional. Specific configuration for the push operation.
pluginStringOptional. Path to a plugin executable.

PullPushConfig

Inherits defaults from UpstreamConfig.

FieldTypeDescription
cwdBooleanOptional.
envfilePathOptional.
varsMap<String, String>Optional.
requiresArrayOptional.
shellStringOptional.
scriptStringOptional. The shell script to execute for the operation.
pluginStringOptional. Path to a plugin executable.

Secret Metadata - .cott.toml

Every encrypted file *.cott.age has a corresponding *.cott.toml metadata file.

Root Fields

FieldTypeDescription
checksumChecksumMetadataAuto generated. Integrity checks for the encrypted data and recipients.
previewPreviewMetadataAuto generated for specific file types. Values-redacted preview of the content.
secretSecretMetadataMetadata about the secret itself.
upstreamMap<String, UpstreamMetadata>Optional. Upstream-specific settings for this secret.

ChecksumMetadata

FieldTypeDescription
encryptedStringBLAKE3 checksum of the encrypted file content (prefixed with blake3:).
recipientsStringBLAKE3 checksum of the recipients used to encrypt the file.

PreviewMetadata

FieldTypeDescription
formatStringOne of: yaml, json, toml, dotenv, ini, hcl.
previewStringThe value-redacted preview content.

SecretMetadata

FieldTypeDescription
timestampStringAuto generated. Last modified timestamp of the secret.
allowArrayOptional. List of glob patterns for allowed recipients.
denyArrayOptional. List of glob patterns for denied recipients.

UpstreamMetadata

FieldTypeDescription
varsMap<String, String>Optional. Secret-specific environment variables for upstream operations.
pullBooleanOptional. Whether to allow pulling this secret from the upstream.
pushBooleanOptional. Whether to allow pushing this secret to the upstream.