Configuration Language

The configuration language is a JSON-based format for declaring your desired development environment. A config is a top-level array of resource objects. Each object represents one tool, application, or system setting that Codify manages.

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. Resources are provided by plugins — see the plugin registry for 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: 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",
    "version": "1.0.0",
    "plugins": {
      "default": "^1.0.0"
    }
  },
  { "type": "ssh" }
]

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

version locks the config to a specific Codify CLI version using semver syntax: >=0.1.0, ^1, 2.3.0.

plugins declares additional plugins and their versions. Plugins must be listed here before their resource types can be used. Local paths (.js or .ts) are also accepted for plugin development.

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"].

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" }.