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

# sauce run

> Compile a program, sign its cook on your Pot, send it and wait for the receipt

`sauce run` compiles a program, builds the cook on the signer's Pot, simulates it, signs it, sends it and waits for the receipt.

## Synopsis

```bash theme={null}
sauce run <file | -> --chain <slug|id> (--keystore <path> | --private-key <hex>) [options]
sauce run <file | -> --chain solana --keypair <path> [--account NAME=<value>]… [options]
```

## Description

`sauce run` compiles the file (a `.sauce.ts` program or an [actions document](https://docs.eco.com/sauce-sdk/cli/actions.md)) and builds the [cook](https://docs.eco.com/sauce/cook.md) on the signer's [Pot](https://docs.eco.com/sauce/pot.md), or on the Pot `--pot` names. The signer is the owner. It simulates the cook first and sends nothing when the simulation fails: it prints the decoded reason and exits `1`. It then signs the cook, sends it, waits for the receipt and prints the transaction hash, status and gas used, the explorer and trace links, what it cost and what moved, or the decoded reason it reverted (exit `1`).

The cook's value defaults to the Kitchen's execution fee, read from the chain. When the program also spends native coin, pass `--value` with the fee plus what it spends; a `--value` below the fee is refused.

The signer is one of `--wallet` (a wallet made with [`sauce wallet`](https://docs.eco.com/sauce-sdk/cli/wallet)), `--keystore`, `--private-key` or, on Solana, `--keypair`. A wallet's `<name>.policy.json`, when present, limits what each transaction moves ([Wallets and policy](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md)).

### What it sends before the cook

You do not deploy the Pot as a separate step: a run deploys it when it first needs it, before it moves any `--fund` tokens in. On an EVM chain, if you send tokens to the Pot yourself instead, deploy it first with [`sauce pot --deploy`](https://docs.eco.com/sauce-sdk/cli/pot): until it is deployed, its address follows the Kitchen ([Funding a Pot](https://docs.eco.com/sauce-sdk/cli/funding.md)). Each transaction the run sends before its cook is a transaction of its own, and the run asks you to approve it at the terminal first:

* deploying your Pot, when it has no code yet (asked as `[deploy/cancel]`, with its gas);
* approving Permit2 for a token `--fund` pulls, the first time (`--fund-mode permit2`); a wallet whose policy limits the token refuses it;
* approving the Pot for the amount `--fund` pulls (`--fund-mode allowance`).

`-y` (`--yes`, or its older name `--auto-approve`) approves each of them without asking and prints `auto-approved: <action>` for each. With no terminal to ask on (CI, a pipe, a program read from stdin with no terminal), or with `--json`, the run sends nothing until they are approved: it names each approval it needs and `--yes`, and exits `1`.

On Solana a missing Pot is created in the cook's own transaction, with nothing asked, when the two fit in one transaction. Otherwise it is asked for like the rest.

On an EVM chain the run holds its whole plan to the [Pot guard](https://docs.eco.com/sauce-sdk/cli/pot.md#the-pot-guard) before it sends the first of these: the Pot must be where the deployed Kitchen puts it, or a deployed Pot the Kitchen created, and a step the guard refuses stops the run before anything is sent. It checks the rest of the plan again before each transaction, since an answer at the terminal can take a while.

### Funding

`--fund TOKEN:amount` gets tokens from your wallet into the Pot in the same cook: the program is wrapped so it first pulls each amount, then runs, then, with `--sweep`, returns what is left. [Funding a Pot](https://docs.eco.com/sauce-sdk/cli/funding.md) covers the amount syntax and each `--fund-mode`.

### Solana

On Solana the run signs with `--keypair` (or a Solana wallet) and reads the Kitchen's fee from the cluster. A missing Pot, and a `pot:<token>` or `owner:<token>` account the cook names that the cluster does not have yet, are created, the owner paying the rent. A program too large for one transaction is staged in a code buffer first and the buffer is closed after the cook. The cook signs the fee it read as its maximum execution fee; `--max-execution-fee` refuses a higher fee before anything is sent. A failure prints the program logs. [Solana](https://docs.eco.com/sauce-sdk/cli/solana.md) covers `--via engine` and the account forms.

### Supported chains

`sauce run` sends only on a supported chain: Ethereum, Base, Arc and Solana, and the testnets Arc Testnet, Base Sepolia, Ethereum Sepolia, Solana Devnet and Solana Testnet. On a preview chain it is refused before anything is read or signed, with a message that names the supported chains and how to request the refused one. `sauce compile` works there, and `sauce simulate` runs wherever the release's engine and Kitchen are deployed.

## Prerequisites

* A signer that holds the chain's native coin for gas and the Kitchen's fee.
* On an EVM chain, the release's engine deployed on the chain. `sauce pot --chain <chain> --owner <address>` reports whether it is.

## Options

| Option | Description |
| - | - |
| `--chain <slug\|id>` | The chain the program runs on (`base`, `8453`, `solana`) |
| `--target <evm\|svm>` | Checked against the chain. `svm` with no `--chain` means Solana |
| `--source-dir <dir>` | The directory the program's relative imports resolve from. Default: beside the file; for stdin, the current directory |
| `--owner <address>` | The Pot's owner, which derives the Pot with the salt (default salt 0) |
| `--salt <label>` | Name one of the owner's Pots: the salt is `keccak256(label)` |
| `--salt-hex <bytes32>` | Give the Pot's salt exactly |
| `--args-json <json\|file>` | `main`'s arguments as one JSON array, inline or in a file |
| `--rpc-url <url>` | Your own RPC endpoint for the chain. Default: a built-in public one |
| `--config <file>` | A file of your own endpoints: `{ "rpcUrls": { "<chain id>": "<url>" } }` |
| `--offline` | Read no chain: no endpoint, built-in ones included |
| `--wallet <name>` | Sign with a wallet of the wallet directory, EVM or Solana |
| `--wallets [<dir>]` | The wallet directory. Default: `~/.sauce/wallets` |
| `--password-env <NAME>` | Read the password from the environment variable `NAME`, the only variable read |
| `--password-file <path>` | Read the password from a file only you can read. Without a password source, it is asked for |
| `--password-command <command>` | Use what this command prints as the password, such as a secret manager's CLI |
| `-y, --yes` | Approve without asking what the run sends before the cook (deploying your Pot, an approval) |
| `--auto-approve` | The same as `--yes`, its older name |
| `--pots <dir>` | The Pot store, where the Pots you deploy are recorded. Default: `~/.sauce/pots` |
| `--json` | Print one JSON object instead |
| `-h, --help` | Show the help |
| `--no-update-check` | Print no notice of a newer `sauce`, and read no registry for one |
| `--args <value>…` | `main`'s arguments in order: an integer as digits, a negative one too (`-5`), JSON for an array or a tuple. Put `--` before a word that starts like a flag |

### EVM chains only

| Option | Description |
| - | - |
| `--pot <address>` | The Pot itself, by address |
| `--value <wei>` | The cook's value: the Kitchen fee plus native coin the program spends. Default: the fee, read from the chain |
| `--keystore <path>` | Sign with a JSON keystore (v3), with a password source |
| `--private-key <hex>` | Sign with a raw key instead. It lands in your shell history |
| `--fund <TOKEN:amount>` | Pull tokens into the Pot in the cook: `USDC:1.5` (whole tokens), `ETH:0.01` |
| `--fund-mode <mode>` | `permit2` (default), `permit`, `allowance` or `transfer` |
| `--sweep` | Return what is left of each funded token afterwards |

### Solana only

| Option | Description |
| - | - |
| `--account NAME=<address>` | An account `main` takes, by name: an address, `pot`, `owner`, `authority` (the account that signs the engine call: the Pot, or the owner with `--via engine`), `system` (the System Program), `pot:USDC` (the Pot's USDC account), `@to:USDC` (the USDC account of `main`'s argument `to`), `mint:USDC`, `program:USDC` (its token program), `slot:@pool:USDC.vaultA` (a pool's account) or `pda:<program>:<seeds>`. Accounts the token methods and venue namespaces add, and those a program derives where it uses them (`Account.pda(…)`), need no flag. A slot derived from the Pot, the owner or the authority takes only the account its derivation gives |
| `--accounts <json\|file>` | The accounts `main` takes as one JSON object of name to value, in `--account`'s forms, inline or in a file |
| `--via <kitchen\|engine>` | The Kitchen's cook on the Pot (default), or the engine's own cook, with no Pot |
| `--max-execution-fee <lamports>` | Refuse a cook whose execution fee is above this |
| `--lookup-table <address>` | An address lookup table holding the cook's accounts. The run creates one when they do not fit |
| `--keypair <path>` | Sign with a keypair file: a JSON array of 64 bytes |

### Low-level options

`--help` lists these apart, with the note "a program's inputs are main's parameters, given with --args".

| Option | Description |
| - | - |
| `--define NAME=VALUE` | A compile-time value for a name the program leaves undeclared: an integer, `0x` hex, `true` or `false`; base58 on Solana |
| `--defines <file.json>` | Compile-time values from a JSON object of name to value. `--define` takes precedence |

## Output

On success, stdout carries the cook's hash, status, gas used and block, its explorer and trace links, its cost (gas, an OP-stack chain's L1 data fee, and the value it carried), and what moved. Questions, notes and `auto-approved:` lines go to stderr. With `--json`, stdout carries one JSON object instead.

Exit codes: `0` when the cook lands and succeeds; `1` when the simulation or the cook reverts, when an approval is needed and was not given, or on a preview chain; `2` for a usage error.

## Examples

The examples use a throwaway wallet, `docs`, made in a scratch directory with `sauce wallet new docs --wallets ./wallets --password-file ./pw.txt`. It holds nothing, and nothing in these examples is sent.

### Stop where approval is needed

With no terminal to ask on, the run names the transaction it would send before the cook, and sends nothing:

```bash theme={null}
sauce run pay.sauce.ts --chain base --wallet docs --wallets ./wallets --password-file ./pw.txt \
  --pots ./pots --args 0x2222222222222222222222222222222222222222 1000000 < /dev/null
```

```text theme={null}
note: wallet docs has no policy, so no limits are set on what it sends: wallets/docs.policy.json sets them (per transaction and per day, by chain, by recipient, native and per token)
sauce run: nothing was sent: this run needs an approval, and there is no terminal to ask on:
  deploy Pot 0xF53Cee7DA32017fA1D88C8FFe7e07738be0203B1
Pass --yes (-y) to approve them (and --password-file with a keystore).
```

The command exits `1`. With `--json`, the same run prints `this run needs an approval, and --json asks nothing`, writes nothing to stdout and exits `1`. Without `--password-file` or another password source, the run stops before that, with `no terminal to ask for the password on: pass --password-env <NAME>, --password-file <path> or --password-command <command>`, and exits `2`.

### Refuse a funded run the wallet cannot pay

```bash theme={null}
sauce run pay.sauce.ts --chain base --wallet docs --wallets ./wallets --password-file ./pw.txt \
  --pots ./pots --fund USDC:1.5 --sweep \
  --args 0x2222222222222222222222222222222222222222 1000000 < /dev/null
```

```text theme={null}
sauce run: 0x2883c72a47e0a86A4E13A048C49b6ADBf1F0D736 holds 0 of USDC (base units), below the 1500000 --fund USDC:1.5 needs
```

The run checks the wallet's balance of each funded token before it sends anything, and exits `1`.

### Refuse a preview chain

```bash theme={null}
sauce run pay.sauce.ts --chain arbitrum --wallet docs --wallets ./wallets --password-file ./pw.txt \
  --pots ./pots --args 0x2222222222222222222222222222222222222222 1000000
```

```text theme={null}
sauce run: sending the cook is refused: it involves arbitrum (Arbitrum One, chain id 42161), a preview chain. The sauce command and its MCP server build and send transactions only on Ethereum, Base, Arc and Solana, and the testnets Arc Testnet, Base Sepolia, Ethereum Sepolia, Solana Devnet and Solana Testnet. On a preview chain they build and send none. A program still compiles there and globals, price, pools and pot's prediction still read; simulate runs wherever the release is deployed on the chain, and says so where it is not.
To ask for Arbitrum One: …
```

The second line names where to ask for the chain. The command exits `1` before it reads the chain or the wallet's key.

## Next steps

* [`sauce simulate`](https://docs.eco.com/sauce-sdk/cli/simulate): the same cook, with no key.
* [`sauce tx`](https://docs.eco.com/sauce-sdk/cli/tx) and [`sauce send`](https://docs.eco.com/sauce-sdk/cli/send): sign with another signer.
* [Funding a Pot](https://docs.eco.com/sauce-sdk/cli/funding.md): `--fund`, `--fund-mode` and `--sweep`.
* [`sauce wallet`](https://docs.eco.com/sauce-sdk/cli/wallet) and [Wallets and policy](https://docs.eco.com/sauce-sdk/cli/wallets-and-policy.md): signers and spending limits.
* [`sauce pot`](https://docs.eco.com/sauce-sdk/cli/pot): the Pot's address and the Pot store.


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