Configuration Language

The Codify configuration language is a JSON-based format for describing your development environment. It consists of an array of resource objects, where each object represents a tool, application, or system setting for Codify to manage.

Example

[
  {
    "type": "homebrew",
    "formulae": ["jq", "openjdk@17", "jenv", "docker"],
    "casks": ["openvpn-connect", "1password", "google-chrome"],
    "os": ["macOS"]
  },
  { "type": "git-lfs" },
  {
    "type": "git-clone",
    "parentDirectory": "~/projects",
    "remote": "git@github.com:kevinwang5658/codify-plugin-lib.git"
  },
  {
    "type": "path",
    "path": "$HOME/projects/dev-tools/bin",
    "dependsOn": ["git-clone"]
  }
]

How it works:

1. Each object in the array is a resource config. The type field identifies which resource to manage. All configs require a type.
2. Resources accept additional parameters that control how they are installed or configured. Parameters can be required or optional — check the individual resource docs for details.
3. Reserved keywords like dependsOn and os are available on every resource. See Keywords for the full list.

Resource Configs

A resource config is a JSON object with a type field added to the top-level array. See the resource reference for all available types.

[
  {
    "type": "homebrew",
    "name": "main",
    "formulae": ["jq", "openjdk@17", "jenv", "docker"],
    "casks": ["openvpn-connect", "1password", "google-chrome"],
    "os": ["macOS"],
    "dependsOn": ["rubyenv"]
  }
]

name uniquely identifies a resource when multiple resources share the same type (for example, two git-clone entries). Codify forms the fully qualified name as type.name. Without a name, Codify assigns a zero-indexed integer automatically if multiple of the same resource exists: git-clone.0, git-clone.1, etc.

dependsOn controls the order resources are applied. Pass an array of fully qualified ids (type.name) or just a type to match all resources of that type.

os restricts a resource to specific operating systems. Resources with an os filter are excluded from plans and applies on non-matching systems.

Project Configs

A project config uses the reserved type "project". It declares metadata and additional plugins for the config file.

[
  {
    "type": "project",
    "description": "A cloud infrastructure environment setup config file",
    "plugins": {
      "default": "^1.0.0"
    }
  },
  { "type": "ssh" }
]

description documents the purpose of the config. It is not used by the CLI.

plugins controls which plugins are loaded and at what version. The default plugin loads automatically at the latest stable version. Use this field to pin it to a specific version, opt into beta, or load a custom plugin from a local file path.

"plugins": {
  "default": "^1.0.0",                  // pin to a version range
  "default": "beta",                    // opt into latest unreleased changes
  "my-custom-plugin": "./my-plugin.ts"  // load a custom plugin
}

Keywords

Resource Configs

• type (required): The resource type identifier. Must start with a letter, followed by alphanumeric characters, underscores, or hyphens. Examples: homebrew, nvm, pyenv, terraform.

• name (optional): Uniquely identifies a resource when multiple resources share the same type. Alphanumeric, underscores, and hyphens allowed. Auto-assigned as 0, 1, 2 when omitted. Examples: "name": "main", "name": "infrastructure-repo".

• dependsOn (optional): Controls apply order. Takes an array of fully qualified ids (type.name) or a bare type. Examples: "dependsOn": ["git-clone.0", "git-clone.1"], "dependsOn": ["path"].

• os (optional): Restricts the resource to specific operating systems. Allowed values: "linux", "macOS", "windows". Examples: "os": ["macOS"], "os": ["linux", "macOS"].

• distro (optional): Further restricts a Linux resource to specific distributions. Allowed values: "debian-based", "rpm-based", "arch", "ubuntu", "debian", "fedora", "rhel", "centos", "alpine", "amzn", "opensuse", "sles", "manjaro", "linuxmint", "pop", "elementary", "kali", "gentoo", "slackware". Example: "distro": ["ubuntu", "debian"].

Project Configs

• type (required): Must be "project".

• description (optional): A human-readable description of the config file. Not used by the CLI. Example: "description": "This is a dependency setup file".

• version (optional): A semver string specifying the minimum Codify CLI version required. Examples: "version": ">=0.5.0", "version": "^1.3".

• plugins (optional): Maps plugin names to version strings. Required before using a plugin's resource types. Accepts local paths for development. Example: "plugins": { "default": "^1.0.0", "custom": "../plugins/dev.ts" }.