> For the complete documentation index, see [llms.txt](https://docs.sail.money/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sail.money/sailor/guides/simulate.md).

# Simulate before going live

`sailor mandate simulate` probes a permission **off-chain** (`eth_call`, no gas) so you can prove it accepts the calls you want and rejects the ones you don't — before authorizing it on-chain or running the agent. This is the single most useful safety step in the Sailor workflow.

## Single call

```bash
sailor mandate simulate \
  --address MyPermission \      # required: address or tracked name
  --sma 0xYourSMA \             # probe as this account (ctx.account); defaults to .sail/account.json
  --target 0xRouter \           # the call target
  --calldata 0x414bf389... \    # 0x-prefixed calldata
  --value 0 \                   # ETH value in wei (default 0)
  --expect pass \               # expected outcome: pass | fail (sets a non-zero exit on mismatch)
  --label "swap usdc->weth"     # human-readable label
```

The command builds a `Context` for the named permission and calls its `evaluate` via `eth_call`. It reports one of:

* **PASS** — the permission returned true; this call would be allowed.
* **FAIL** — the permission returned false; this call would be denied (fail-closed).
* **REVERT** — `evaluate` reverted (treated by the kernel as denial).

`--expect pass|fail` makes the command exit non-zero on a mismatch, so you can assert behavior in scripts and CI.

## Batch

Probe many calls at once with a JSON file:

```bash
sailor mandate simulate --address MyPermission --sma 0xYourSMA --calls ./samples.json
```

```json
[
  { "target": "0xRouter", "calldata": "0x414bf389...", "value": "0", "expect": "pass", "label": "in-bounds swap" },
  { "target": "0xRouter", "calldata": "0x...big...",   "expect": "fail", "label": "over the cap" },
  { "target": "0xEvil",   "calldata": "0x...",         "expect": "fail", "label": "wrong target" }
]
```

Each entry takes `target`, `calldata`, optional `value`, `expect`, and `label`. Add `--json` to the command for machine-readable results. Build your samples from the real strategy: include the calls the agent will make (expect pass) **and** the calls it must never make (expect fail).

## Where it fits

The rule the scaffold enforces — and you should too — is: **never authorize (attach) a permission before `forge test` and `sailor mandate simulate` both pass** against samples derived from your strategy. Simulation closes the gap between "the contract compiles" and "the contract bounds exactly what I intend."

You can also preview a dispatch through the SDK at runtime with `client.dispatch.preview(...)`, which runs the kernel's `previewBatch` view and returns `{ approved, reason }`. See [SailorClient](/sailor/sdk/client.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sail.money/sailor/guides/simulate.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.