cottage Configuration Specification

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

Project Configuration - cottage.toml

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

Field	Type	Description
`upstream`	Map<String, UpstreamConfig>	Optional. Defines upstream configurations for pulling/pushing secrets.

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

Field	Type	Description
`cwd`	Boolean	Optional. If true, run the script in the directory of the secret.
`envfile`	Path	Optional. Path to an encrypted file to use as environment variables for the script.
`vars`	Map<String, String>	Optional. Environment variables to pass to the script.
`shell`	String	Optional. The shell to use for running scripts (default: `sh`).
`pull`	PullPushConfig	Optional. Specific configuration for the pull operation.
`push`	PullPushConfig	Optional. Specific configuration for the push operation.
`plugin`	String	Optional. Path to a plugin executable.

Inherits defaults from UpstreamConfig.

Field	Type	Description
`cwd`	Boolean	Optional.
`envfile`	Path	Optional.
`vars`	Map<String, String>	Optional.
`shell`	String	Optional.
`script`	String	Optional. The shell script to execute for the operation.
`plugin`	String	Optional. Path to a plugin executable.

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

Field	Type	Description
`checksum`	ChecksumMetadata	Auto generated. Integrity checks for the encrypted data and recipients.
`preview`	PreviewMetadata	Auto generated for specific file types. Values-redacted preview of the content.
`secret`	SecretMetadata	Metadata about the secret itself.
`upstream`	Map<String, UpstreamMetadata>	Optional. Upstream-specific settings for this secret.

Field	Type	Description
`encrypted`	String	BLAKE3 checksum of the encrypted file content (prefixed with `blake3:`).
`recipients`	String	BLAKE3 checksum of the recipients used to encrypt the file.

Field	Type	Description
`format`	String	One of: `yaml`, `json`, `toml`, `dotenv`, `ini`, `hcl`.
`preview`	String	The value-redacted preview content.

Field	Type	Description
`timestamp`	String	Auto generated. Last modified timestamp of the secret.
`allow`	Array	Optional. List of glob patterns for allowed recipients.
`deny`	Array	Optional. List of glob patterns for denied recipients.

Field	Type	Description
`vars`	Map<String, String>	Optional. Secret-specific environment variables for upstream operations.
`pull`	Boolean	Optional. Whether to allow pulling this secret from the upstream.
`push`	Boolean	Optional. Whether to allow pushing this secret to the upstream.