# Revise an installed setup

Review a goal or profile change before replacing managed files.

Canonical page: https://bowerloom.ai/docs/revision/

Version: 0.7.0-beta.1 · Release: v0.7-beta.

[Source repository](https://github.com/sageadvicellc/bowerloom) · [Current support and limits](https://bowerloom.ai/docs/status/)

Revision changes an installed setup through another exact plan. It retains private history and preserves unrelated project files.

Open beta · 0.7.0-beta.1

Setup does not start workers, grant runtime access, or authorize connected actions.

Keep your project out of iCloud Drive folders. Project commands such as `bowerloom up`, `ls`, `status`, `apply`, and `skills sync` refuse a project under `~/Documents` or `~/Desktop` when Desktop and Documents sync is on, and under the `~/Library` cloud folders, with `PROJECT_IN_CLOUD_FOLDER`. The older forms that take an explicit path do not run this check. This beta reads skills only from public sources. See the [beta limits](/docs/guides/add-skills/#current-beta-limits).

## Ask your agent

```text
Help me revise my installed Bowerloom setup. Read its current state and show the replacement plan. Wait for my exact approval.
```

## Agent procedure

### Prerequisites

Install the matching CLI version through [Install Bowerloom](/docs/start/).

`bowerloom revise` refuses once a project holds content added after setup. The fix comes in a later 0.7 release. Use revision on a project that only holds the setup files.

Use the original target and a readable installation receipt. Resolve any pending revision before starting another change.

### Prepare a revised goal

Read the current status first:

```sh
bowerloom init status --target /absolute/projects/clean-install-trial
```

Replace the example target with the installed project's absolute path. Plan the selected change:

```sh
bowerloom revise plan --target /absolute/projects/clean-install-trial --name "Clean install trial" --goal "Revise the project plan for accessibility review" --profile engineer --json
```

Read the old goal, new goal, proposed files, replacement scope, old installation revision, and new plan revision.

The CLI accepts these inline fields. Its help also documents the alternative `--brief` form. Do not mix the two forms.

### Approve the exact replacement

Wait for human approval of the new plan. Replace `OLD_INSTALLATION_REVISION` with the installed revision recorded in that plan.

Replace `EXACT_REVISION_PLAN` with the new plan's complete revision. Keep all brief inputs identical.

```sh
bowerloom revise apply --target /absolute/projects/clean-install-trial --name "Clean install trial" --goal "Revise the project plan for accessibility review" --profile engineer --from OLD_INSTALLATION_REVISION --approve EXACT_REVISION_PLAN
```

### Inspect the result

```sh
bowerloom init status --target /absolute/projects/clean-install-trial
```

Report the actual resulting installation revision and readiness fields. The resulting revision is distinct from the approved change plan.

The operation replaces managed setup files and preserves the recorded previous installation in private history. It starts no workers.

The private history lives in the project folder, next to `.bowerloom`, in `.bowerloom-revision-<revision>/`. Its `previous` folder holds the earlier setup files, including the earlier `installation-receipt.json`. While a revision is pending, `.bowerloom-revision.json` marks it. Keep both out of version control. [What to commit](/docs/guides/add-skills/#what-to-commit) gives the `.gitignore` lines.

### If the revision stops partway

If status is `revision-pending`, preserve the marker, stage, and backup. Follow [Recover an interrupted revision](/docs/guides/recover-revision/).

If identity, old revision, or inputs differ, stop and inspect. Do not edit a receipt to clear the refusal.

## Review dependent access again

An old connection or runtime enrollment does not authorize a revised specification. Review those exact bindings before later execution.

## Support boundary

[Current support](/docs/status/) describes supported tasks and limits. [Plans and approval](/docs/permissions/) explains changed inputs.