codify.jsonc file

The codify.jsonc file defines the desired applications, programs, CLI tools, paths, etc. that the CLI should install on the system. Config files must follow the naming pattern *.codify.<extension> (e.g., codify.jsonc, my-setup.codify.json).

Example File

[
  {
    "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"]
  }
]

The codify.jsonc file is top level json array [] with child objects representing individual configs which defines resources.

Parts of the file

1. This config block defines a homebrew resource. A resource is anything that can be installed on the operating system. It is specified in a codify.jsonc file using the keyword type. All config blocks must have a type field.

2. Resources can have additional parameters that configure installation or configuration options. For the git-clone resource, we can specify the parent directory to clone into and the remote repository to clone from. Parameters can be optional or required. In this example, remote is a required parameter for the git-clone resource. For more information on the git-clone resource, visit here.

3. Reserved keywords like dependsOn and os are available to all resources. dependsOn specifies dependencies between resources to control execution order. os restricts a resource to specific operating systems. For a full list of resource keywords, visit here.

Resource configs

Resource configs form the majority of configs found in a codify.jsonc file. A resource config is defined by adding a json object with a type { type: "resource-type-id" } into the top level array. Resources provide Codify the ability to refresh, apply, modify and destroy packages on macOS.

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

Resources are provided by individual plugins and the available resources must be looked up in the plugin registry.

A name parameter can be added to a resource to fully qualify it. Names are useful for referencing a specific resource when multiple resources of the same type are in a config (e.g., multiple git clones). Codify combines the type and name with a . to form the fully qualified name. If there are multiple resources of the same type but no name is defined, a zero-indexed integer will be used for the name. For example: git-clone.0, git-clone.1, git-clone.2

A dependsOn parameter can be added to control the order that resources are applied. Use "dependsOn": [] with a fully qualified id (type.name) to specify explicit dependencies.

An os parameter can be added to restrict a resource to specific operating systems. When running on a different OS, the resource will be filtered out and not included in plans or applies.

Project Configs

In addition to resource configs, a codify.jsonc file can also have project configs. Project configs are denoted by "type": "project". The type project is reserved.

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

Project configs are mainly used to add additional plugins and specify metadata for a codify.jsonc file.

A description can be added to describe the purpose of the codify.jsonc file.

A version semver parameter can be added to lock the version of the Codify CLI that is applying the file. See standard semver syntax like >=0.1.0, ^1, 2.3.0 to specify the version.

Keywords

Resource Configs

• type (required): Specifies the resource type. Types are dynamic and based on the resource types provided by each plugin. Must start with a letter followed by alphanumeric characters, underscores, or hyphens. Some types provided by the default plugin include: homebrew, nvm, pyenv, terraform, etc.

• name (optional): Uniquely identifies a resource when there are multiple resources of the same type. Names must be alphanumeric with underscores or hyphens allowed. A zero-indexed integer name (0, 1, 2) is automatically generated when multiple resources of the same type have no names. Examples: "name": "main", "name": "infrastructure-repo".

• dependsOn (optional): Specifies the order resources should be applied in. Takes an array of fully qualified ids (type.name) or just a type (which matches all resources of that type). Examples: "dependsOn": ["git-clone.0", "git-clone.1"], "dependsOn": ["path"]

• os (optional): Specifies which operating systems this resource applies to. When specified, the resource will only be included in plans and applies when running on a matching OS. Allowed values: "linux", "macOS", "windows". Examples: "os": ["macOS"], "os": ["linux", "macOS"]

Project Configs

• type (required): To define a project config, the type must be "project".

• description (optional): A description of the project. This property is not used by Codify CLI. Example: "description": "This is a dependency setup file"

• version (optional): A semver string that specifies the version of Codify CLI required to apply the config. Examples: "version": ">=0.5.0", "version": "^1.3".

• plugins (optional): An object mapping plugin names to version strings. Plugins must be declared in the project.plugins section before their resources can be used. Local file paths (.js or .ts) can also be specified for local plugin development. Example: "plugins": { "default": "^1.0.0", "custom": "../plugins/dev.ts" }