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

# Transactions and file tools

> Transactions, rollback, save-state inspection, save-location prompting, autosave, and guarded Python execution.

Transactions, rollback, save-state inspection, save-location prompting, autosave, and guarded Python execution.

Tool count: `12`.

Client note: `ctx` is injected by the MCP server and is not supplied as a user argument.

## `autosave`

Signature:

```python theme={null}
autosave(doc_name: str | None = None, fallback_dir: str | None = None) -> list[TextContent]
```

Descriptor:

```text theme={null}
Save Parashell documents to disk.

Saves the active document, a named document, or all open documents. Documents
that already have a file path are saved in place. Documents without a stored
path are written as <Name>.FCStd into fallback_dir, or into your home
directory (e.g. C:\Users\<you> on Windows) when fallback_dir is omitted.
Runs automatically before every execute_code call.

Args:
    doc_name: Name of a specific document to save. If omitted, all open
        documents are saved.
    fallback_dir: Directory used to save documents that have no FileName
        yet. If omitted, the user's home directory is used.
```

## `execute_code`

Signature:

```python theme={null}
execute_code(code: str, reason: str, expected_action: str, transaction_id: str) -> list[TextContent | ImageContent]
```

Descriptor:

```text theme={null}
Execute arbitrary Python code in Parashell.

Parashell exposes a FreeCAD-compatible Python API. Import the API
under its original module names inside the snippet - use 'import FreeCAD' and
'import FreeCADGui' with the FreeCAD-compatible API. Object TypeIds (e.g.
'Part::Box', 'PartDesign::Body') are FreeCAD-compatible.

Every model edit must run inside an open transaction. Open one with
transaction_create, pass its id here, then transaction_apply to persist the
changes or transaction_cancel to roll them back.

Args:
    code: The Python code to execute inside Parashell's interpreter.
    reason: A non-technical, straight-to-the-point explanation of why you
        are running this code. Must be between 10 and 25 words.
    expected_action: A non-technical, straight-to-the-point description of
        the expected output and logic. Must be between 5 and 15 words.
    transaction_id: Id of the open transaction returned by transaction_create.
```

Failure behavior: if the snippet raises, only the objects created by that failed
call are removed and the document is recomputed. Edits from earlier successful
calls in the same open transaction are preserved, and the transaction stays open
so you can continue or cancel it explicitly with transaction\_cancel. The response
lists what was reverted; nothing is saved on failure, so a failed run never leaves
new partial objects behind for the next autosave to persist. Execution waits for
the queued GUI task to finish; it does not report a timeout while the same code
continues mutating the document in the background.

## `is_file_saved`

Signature:

```python theme={null}
is_file_saved(doc_name: str | None = None) -> list[TextContent]
```

Descriptor:

```text theme={null}
Report whether a document is saved to a file on disk.

Args:
    doc_name: Document to check. If omitted, the active document is used.
```

## `request_file_save`

Signature:

```python theme={null}
request_file_save(doc_name: str | None = None, suggested_name: str | None = None) -> list[TextContent]
```

Descriptor:

```text theme={null}
Ask the user where to save a model via a save-location prompt.

Opens a dialog letting the user pick a folder and a file name (the .FCStd
extension is fixed), then saves the document there. Use this when a model has
no save location yet so applied changes persist where the user wants. Returns
where the model was saved, or that the user cancelled.

Args:
    doc_name: Document to save. If omitted, the active document is used.
    suggested_name: Optional default file name to pre-fill (without extension).
```

## `rollback_to_transaction`

Signature:

```python theme={null}
rollback_to_transaction(transaction_id: str) -> list[TextContent | ImageContent]
```

Descriptor:

```text theme={null}
Hard-reset a document to the exact state before an applied transaction.

Like reverting a commit and every commit above it: restores the pre-change
checkpoint captured before the given transaction opened, discarding the target
transaction's edits and every later change. Transactions newer than the target
are marked cancelled. Restoration verifies document identity and the checkpoint
object set before autosave. This destroys applied work - confirm with the user
before using it when changes would be lost.

Args:
    transaction_id: Id of the applied transaction whose changes should be removed.
```

## `transaction_apply`

Signature:

```python theme={null}
transaction_apply(transaction_id: str) -> list[TextContent | ImageContent]
```

Descriptor:

```text theme={null}
Apply an open transaction: commit its changes, recompute, and save.

Finalizes every edit made under the transaction as a single atomic change,
recomputes the document, and autosaves it (to its existing path, or to your
home directory as <Name>.FCStd if it has none). The transaction becomes
'applied'.

Args:
    transaction_id: Id of the open transaction to apply.
```

## `transaction_cancel`

Signature:

```python theme={null}
transaction_cancel(transaction_id: str) -> list[TextContent | ImageContent]
```

Descriptor:

```text theme={null}
Cancel a transaction and roll back its changes.

For an open transaction this aborts and undoes every change made under it.
For an already-applied transaction it undoes the committed change (only
possible if no newer transaction sits on top of it). The transaction becomes
'cancelled' and can then be removed with transaction_delete.

Args:
    transaction_id: Id of the transaction to cancel.
```

## `transaction_create`

Signature:

```python theme={null}
transaction_create(doc_name: str, label: str | None = None, reason: str | None = None) -> list[TextContent]
```

Descriptor:

```text theme={null}
Open a new transaction against a document and get its id.

Transactions work like Terraform: open one here, route every edit
(create_object, edit_object, delete_object, insert_part_from_library,
execute_code, and any other model change) through its id while it is open,
review the pending changes with transaction_plan, then transaction_apply to
persist and save them or transaction_cancel to roll everything back. Creation
writes a pre-change file checkpoint before opening the native transaction and
fails safely if that checkpoint cannot be created. Only one transaction can be
open per document at a time.

Args:
    doc_name: Document to open the transaction on.
    label: Optional human label for the transaction.
    reason: Optional explanation of what this transaction is for.
```

## `transaction_delete`

Signature:

```python theme={null}
transaction_delete(transaction_id: str) -> list[TextContent]
```

Descriptor:

```text theme={null}
Permanently remove a transaction record.

Only cancelled transactions can be deleted; cancel an open or applied
transaction first. This purges the bookkeeping record only - the document is
not modified.

Args:
    transaction_id: Id of the cancelled transaction to delete.
```

## `transaction_get`

Signature:

```python theme={null}
transaction_get(transaction_id: str) -> list[TextContent]
```

Descriptor:

```text theme={null}
Get the full record of a single transaction, including its operation log.

Args:
    transaction_id: Id of the transaction to inspect.
```

## `transaction_list`

Signature:

```python theme={null}
transaction_list(doc_name: str | None = None) -> list[TextContent]
```

Descriptor:

```text theme={null}
List tracked transactions and their status.

Args:
    doc_name: Optional document to filter by. If omitted, lists all
        transactions across every document.
```

## `transaction_plan`

Signature:

```python theme={null}
transaction_plan(transaction_id: str) -> list[TextContent]
```

Descriptor:

```text theme={null}
Preview the pending changes of a transaction without persisting them.

Returns a Terraform-style plan of what would change on apply: objects to add,
change, and destroy, plus the recorded operation log. Safe to call repeatedly.

Args:
    transaction_id: Id of the transaction returned by transaction_create.
```