> ## Documentation Index
> Fetch the complete documentation index at: https://orchard.andrewshawcare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchard commands: provision.sh, scaffold.sh, test.sh

> Reference for every Orchard command: provision.sh to set up your machine, scaffold.sh to create new modules, and test.sh to verify your setup.

Orchard exposes three commands you interact with directly: `provision.sh` to run the full workstation setup, `scaffold.sh` to generate a new module skeleton, and `test.sh` to verify the current state of your machine. Everything else runs automatically inside those scripts.

***

## provision.sh

`provision.sh` is the main entry point for Orchard. Running it executes every install module in sequence, then runs the full test suite to confirm everything completed successfully. You run this once to set up a new machine, and can safely re-run it at any time — modules that are already installed are skipped.

**Usage**

```bash theme={null}
./provision.sh
```

<Warning>
  You must run this command from the root of the cloned Orchard directory. Running it from another location will cause the script to fail because it resolves module paths relative to its own location.
</Warning>

**Requirements**

* macOS
* An active internet connection (needed to download Homebrew, packages, and applications)

**What it does**

`provision.sh` runs the following modules in order:

| Order | Module                 | What it installs or configures                                             |
| ----- | ---------------------- | -------------------------------------------------------------------------- |
| 1     | `brew`                 | Installs Homebrew if not already present, and disables analytics           |
| 2     | `brew-packages`        | Installs command-line packages listed in `brew-packages/package-list.bash` |
| 3     | `cask-packages`        | Installs GUI applications listed in `cask-packages/package-list.bash`      |
| 4     | `dockutil`             | Installs the `dockutil` CLI used to manage Dock entries                    |
| 5     | `dock`                 | Configures Dock settings and removes default Apple apps                    |
| 6     | `mac-app-store`        | Installs apps from the Mac App Store via `mas`                             |
| 7     | `finder`               | Configures Finder preferences                                              |
| 8     | `keyboard`             | Applies keyboard settings                                                  |
| 9     | `mouse`                | Applies mouse settings                                                     |
| 10    | `trackpad`             | Applies trackpad settings                                                  |
| 11    | `security-and-privacy` | Applies security and privacy preferences                                   |
| 12    | `bats`                 | Installs the Bats testing framework                                        |
| 13    | `claude-code`          | Installs Claude Code if not already in your `PATH`                         |

After all modules run, `provision.sh` automatically calls `test.sh` to validate the result.

**What success looks like**

Each module prints its progress to the terminal. After all modules complete, you will see Bats test output confirming each module's tests passed. The script exits with code `0` and returns you to the shell prompt with no error output.

<Tip>
  `provision.sh` is safe to re-run. Homebrew skips packages that are already installed, and modules like `claude-code` check for an existing installation before doing anything. If a run fails partway through, fix the error and run `./provision.sh` again.
</Tip>

***

## scaffold.sh

`scaffold.sh` creates a new module directory with a ready-to-edit `install.sh` script and a `test.bats` test file. Use it whenever you want to add a new provisioning module to Orchard.

**Usage**

```bash theme={null}
./scaffold.sh <resource-name>
```

**Arguments**

<ParamField path="resource-name" type="string" required>
  The name of the new module. This becomes the directory name. Use lowercase kebab-case to match the existing module naming convention (for example, `git-config` or `ssh-keys`).
</ParamField>

**Example**

```bash theme={null}
./scaffold.sh git-config
```

This creates the following files:

```
git-config/
├── install.sh    # Executable shell script, ready to edit
└── test.bats     # Bats test file with a placeholder failing test
```

The generated `install.sh` contains a single shebang line with `set -euo pipefail` already set. The generated `test.bats` contains one placeholder test that fails by design — a reminder to write a real test before running `provision.sh`.

**What success looks like**

The command exits silently with no output. You will see the new directory appear in the Orchard root. Open `<resource-name>/install.sh` to write your installation logic, and `<resource-name>/test.bats` to write the corresponding test.

<Note>
  After scaffolding a new module, you must manually add it to the `install_scripts` array in `provision.sh` for it to run during provisioning.
</Note>

***

## test.sh

`test.sh` runs the Bats test suite across all modules. `provision.sh` calls it automatically at the end of a full provisioning run, but you can also run it independently at any time to check the current state of your machine.

**Usage**

```bash theme={null}
./test.sh
```

**What it does**

`test.sh` first ensures `bats` is installed by running `bats/install.sh`, then discovers and runs every `test.bats` file found in the module directories.

**What success looks like**

Bats prints one line per test. Passing tests are prefixed with `✓` and failing tests with `✗`. A fully provisioned machine should show all tests passing with exit code `0`.

```
✓ brew is installed
✓ devcontainer is installed
✓ Visual Studio Code is installed
✓ claude is installed
...
```

If any test fails, Bats prints the test name, the failing assertion, and exits with a non-zero code.