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

# Setup file tools

> Preview, apply and undo an ALLOCAIT.md.

Three tools preview, apply and undo a setup file. Preview first, show the result to the user, and apply only after they say yes.

A setup file is one Markdown file of definitions: scenarios with their ranges, custom asset classes, watchlists, Inputs, and one portfolio's playbooks, monitors and charts. It never holds a holding, cash, price, recorded value or the active scenario. See [ALLOCAIT.md](https://docs.allocait.app/concepts/setup-file.md) for what you see and the steps an agent follows.

## The flow

**1. Preview**

Call `preview_setup` with the file text. It writes nothing, and a read-only connection can use it.

**2. Ask the user**

Show the preview and ask. The digest ties an apply to a preview of the same decisions. It doesn't show that anyone read the preview.

**3. Apply**

Call `apply_setup` with the same file, the same `portfolio_id` and the preview's `digest`.

**4. Undo, if asked**

Call `undo_setup`. It shows what would go unless `dry_run` is `false`.

## Tools

**preview\_setup** `read`

Shows what an `ALLOCAIT.md` setup file would add to your account and what stays yours. Writes nothing, and a read-only connection can use it. The result opens with `digest` and `can_apply`, then `file` (its id, name, author, revision, description and `disclosure`, and your newest earlier import of it), `note` (Allocait's own sentence about the numbers in a file), `target` (the portfolio its playbooks, monitors and charts go to), `counts` (`new`, `update`, `same`, `kept` and `left_out`), `items` (each with its `kind`, `name`, `status` and `reason`, and the details that explain it), `issues` (warnings), `unlisted_symbols` and `key`, which says what each status and reason means. With several portfolios and a file that has a `portfolio` block, `choose_portfolio` lists them; ask the user which. A file with errors comes back as `INVALID_INPUT` with every error in `issues`. Rules text is refused, with a pointer to `preview_rules`. Key arguments: `setup` (the whole file text, from the opening `---`), optional `portfolio_id`.

**apply\_setup** `write, destructive`

Applies a setup file exactly as `preview_setup` showed it. It adds what the preview marked new, and updates only what an earlier import of the same file made and you haven't changed. It never overwrites something you made, deletes an item, or writes a holding, cash, price, recorded value or active scenario. Returns a `receipt_id` for `undo_setup`, and each item it created carries its `object_id`. It never makes a scenario active: `save_portfolio` does that, when you ask. If your account changed since the preview, it writes nothing and returns `CONFIRMATION_REQUIRED` with a fresh preview. The digest ties an apply to a preview of the same decisions; it doesn't show that anyone read the preview. Ask the user first, and don't apply with no one to ask. Key arguments: `setup` and `portfolio_id` (as previewed), `digest` (from `preview_setup`).

**undo\_setup** `write, destructive`

Undoes an applied setup file: removes what it added that you haven't changed or used, puts back what it updated, and keeps the rest. Recorded values stay. Only a file's newest import can be undone; a later import of the same file blocks it with `IN_USE` and `later_receipt_id`. It shows what would go unless `dry_run` is `false`. Key arguments: optional `receipt_id` (default: the newest import), optional `dry_run` (default `true`).

## Next steps

> [card] [ALLOCAIT.md](https://docs.allocait.app/concepts/setup-file.md)
>
> What a setup file holds and how the review works.

> [card] [Rule tools](https://docs.allocait.app/claude/tools/rules.md)
>
> Change one class or a whole scenario's rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.