Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ton-blockchain/acton/llms.txt

Use this file to discover all available pages before exploring further.

acton script executes a standalone Tolk script file. Scripts are the standard Acton mechanism for deployment flows, blockchain queries, and one-off operational tasks. They differ from tests in that they define a main() entry point and can send real on-chain transactions when --net is provided. Without --net the script runs entirely in the local TVM emulator, making it safe to iterate on before committing to a broadcast.

​
Synopsis

acton script [OPTIONS] <PATH> [ARGS...]
Arguments after <PATH> are forwarded to the script’s main() function. Insert -- before script arguments that look like flags to prevent Acton from parsing them: 
acton script scripts/query.tolk -- --net-like-value

​
Arguments & options

​
Positional

ArgumentDescription
<PATH>Path to the Tolk script file to execute.
[ARGS...]Arguments parsed against the main() ABI and passed to the script.

​
Script options

FlagTypeDefaultDescription
--verbosecount0Increase executor log verbosity to level 1. Useful for debug.dumpStack() output.

​
Debugging

FlagTypeDefaultDescription
--debugflagfalseEnable debug mode.
--backtrace <LEVEL>full—Enable execution backtraces. Currently full is the only supported level.
--debug-port <PORT>u1612345Port for the debug server.

​
Cache

FlagTypeDefaultDescription
--clear-cacheflagfalseClear the compilation cache before running.

​
Remote

FlagTypeDefaultDescription
--fork-net <NETWORK>string—Fork blockchain state from a remote network for local execution. When --net is set, an omitted --fork-net defaults to that broadcast network. Conflicting values are rejected.
--fork-block-number <SEQNO>u64—Historical block sequence number to fork from.

​
Broadcasting

FlagTypeDefaultDescription
--net <NETWORK>string—Broadcast to the selected network. When omitted, the script runs in emulation mode.
--tonconnectflagfalseUse TON Connect wallet approval for broadcast messages instead of local wallet mnemonics. Saves the session to build/sessions/tonconnect/<network>.json.
--tonconnect-port <PORT>u1652258Port for the local TON Connect page. Keep stable across runs for the same project so injected wallets recognise the local dApp.
--explorer <NAME>tonscan | toncx | dton | tonviewer—Explorer to use for transaction links printed after a broadcast.

​
Output

FlagTypeDefaultDescription
--show-bodiesflagfalseShow decoded message bodies in printed transaction trees when ABI is known.

​
Global flags

FlagTypeDefaultDescription
--color <WHEN>auto | always | neverautoControl coloured output.
--manifest-path <PATH>path—Path to Acton.toml. Conflicts with --project-root.
--project-root <PATH>path—Path to project root. Conflicts with --manifest-path.

​
Script model

ModeBehaviour
Emulation (default)Executes locally using emulator wallets. No network access.
--fork-netResolves remote blockchain state but keeps execution local.
--netBroadcasts real transactions. Reads wallet keys from wallets.toml.
--net --tonconnectBroadcasts through a connected TON Connect wallet.
Wallet names referenced in the script are resolved from wallets.toml, with local entries overriding global.wallets.toml. With --tonconnect, any scripts.wallet("name") call resolves to the connected wallet address.

​
Argument forwarding

Forwarded arguments are parsed against the ABI for main():
TypeSyntax
Integers42, -1, 0xff, 0b1010
Booleanstrue, false
Nullablenull
cell / slice / bitsNPlain BoC hex without C{} or CS{} prefixes
Arrays[item1, item2]
The number of CLI arguments must exactly match the main() parameters. Unsupported types include struct, tuple, map, dict, builder, any_address, and other complex types.

​
Safe execution order

Before broadcasting to a live network, follow this sequence: 
# 1. Build
acton build

# 2. Test
acton test

# 3. Dry-run in emulator
acton script scripts/deploy.tolk

# 4. Broadcast to testnet
acton script scripts/deploy.tolk --net testnet

# 5. (When confident) broadcast to mainnet
acton script scripts/deploy.tolk --net mainnet

​
TonCenter API keys

Built-in networks read:
  • TONCENTER_MAINNET_API_KEY for mainnet
  • TONCENTER_TESTNET_API_KEY for testnet
Custom networks (custom:<name>) read <NORMALIZED_NAME>_API_KEY. Acton loads .env automatically — keep keys there rather than passing them inline.

​
Examples

acton script scripts/deploy.tolk
--net sends real on-chain transactions. Always test your script in emulation mode first, then on testnet, before using --net mainnet.

Build docs developers (and LLMs) love

Get started for freeTalk to us