Docs
Command reference

acton script

Reference manual for the acton script command

Synopsis

acton script [options] path [args...]

Description

Execute a standalone Tolk script.

Scripts are useful for experimentation, deployment flows, blockchain queries, and one-off operational tasks. Unlike tests, scripts use a main() entry point and can send real transactions when --net is provided.

Options

Script Options

<path>

Path to the script file to execute.

<args>...

Arguments parsed against the main() ABI and passed to the script.

Repeatable:

May be passed multiple times.

--verbose

Enable executor debug logs at verbosity level 1.

Currently only level 1 is supported. Pass --verbose at most once. Use this for low-level executor output such as debug.dumpStack(). For richer debug output, use --backtrace full or --debug.

Default:

0

Repeatable:

May be passed multiple times.

Debugging Options

--debug

Enable debug mode.

--backtrace<level>

Enable execution backtraces.

Currently supported value: full.

Possible values:

full

--debug-port<port>

Debug server port.

Default:

12345

Cache Options

--clear-cache

Clear the compilation cache before running.

Remote Options

--fork-net<network>

Fork blockchain state from a remote network for local execution. When --net is set, omitted --fork-net defaults to the selected broadcast network.

--fork-block-number<seqno>

Historical block sequence number to fork from.

When a fork block number is set, Acton caches resolved remote accounts under build/cache/<network>/<seqno>/<workchain>_<address-hash>.json. Later script runs with the same fork network, block number, and address read that file before calling the remote API.

--no-fork-cache

Disable persistent account cache for pinned fork block numbers. Use this when you want every script run to fetch forked accounts from the remote API. The regular --clear-cache flag removes this cache together with the rest of build/cache.

Broadcasting Options

--net<network>

Broadcast to the selected network. If omitted, the script runs in emulation mode. Conflicting --net and --fork-net values are rejected.

--tonconnect

Use TON Connect wallet approval for broadcast messages.

This opens a local browser page, connects a wallet, and sends net.send(...) messages through that wallet instead of loading local wallet mnemonics. The TON Connect session is saved under build/sessions/tonconnect/<network>.json and reused by later runs in the same project. Currently supported only with --net mainnet or --net testnet.

--tonconnect-port<port>

Local TON Connect page port. Defaults to 52258.

Acton keeps this port stable so injected wallets can recognize the same local dApp on later runs. If the default port is busy, pass another port explicitly and keep using the same value for that project.

Default:

52258

--explorer<name>

Explorer to use for transaction links.

Possible values:

tonscan, toncx, dton, tonviewer

Output Options

--show-bodies

Show decoded message bodies in printed transaction trees when ABI is known.

Display Options

--color<when>

Control when to use colored output.

Possible values:

auto, always, never

Default:

auto

Project Options

--manifest-path<path>

Path to the Acton.toml file to use for this invocation.

Use this when running the command outside the project directory or when the manifest lives at a non-default location.

Conflicts with:

--project-root

--project-root<path>

Path to the project root to use for configuration discovery and relative defaults.

Conflicts with:

--manifest-path

Script Model

A Tolk script defines a main() function and runs as an isolated execution.

  • state is not preserved between runs
  • local execution uses emulator wallets and balances
  • --fork-net keeps execution local but resolves remote state
  • --net sends real transactions using configured wallets
  • --net ... --tonconnect sends real transactions through the connected TON Connect wallet

Wallet names referenced by the script are resolved from the merged wallet configuration, with local wallets.toml entries overriding global.wallets.toml on name conflicts. With --tonconnect, any scripts.wallet("name") call resolves to the connected wallet address. Acton saves the TON Connect session in build/sessions/tonconnect/<network>.json, so the next script run can restore the wallet connection without asking the user to connect again.

Argument Forwarding

Arguments after _path_ are passed through to the script runtime.

If a forwarded argument could be mistaken for an Acton flag, insert -- before the script arguments:

acton script scripts/query.tolk -- --net-like-value

Script Arguments

Forwarded arguments are parsed against the ABI for main().

  • the number of CLI arguments must exactly match the main() parameters
  • integers use Tolk integer literal syntax such as 42, -1, 0xff, and 0b1010
  • bool accepts true and false
  • nullable supported types accept null
  • cell, slice, and bitsN accept plain BoC hex without C{} or CS{} prefixes
  • any_address accepts an internal address or the addr_none literal
  • arrays accept [item1, item2]

Unsupported parameter types currently include structs, tuple, map, dict, builder and other complex types.

Side Effects

acton script always compiles and executes the selected script. With --net, it can send real blockchain transactions; without --net, execution stays local even when --fork-net is used.

Executor debug logs are hidden by default. Re-run with --verbose when you need level-1 executor output such as debug.dumpStack().

Exit Status

  • 0: The script completed successfully, including successful broadcast flows.
  • 1: Script execution failed, broadcast submission failed, or remote network access such as fork-state resolution failed.

Safe Execution Order

When a script can affect on-chain state, the usual safe sequence is:

  1. acton build
  2. acton test
  3. acton script <path> without --net
  4. only then acton script <path> --net testnet

Examples

  1. Execute locally in the emulator:

    acton script scripts/deploy.tolk

  2. Show executor debug logs from debug.* helpers:

    acton script scripts/deploy.tolk --verbose

  3. Broadcast to testnet:

    acton script scripts/deploy.tolk --net testnet

  4. Query mainnet state without broadcasting:

    TONCENTER_MAINNET_API_KEY=your-key acton script query.tolk --fork-net mainnet

  5. Broadcast a deploy flow and print explorer links:

    acton script scripts/deploy.tolk --net testnet --explorer tonscan

  6. Broadcast through TON Connect instead of local wallet keys:

    acton script scripts/deploy.tolk --net testnet --tonconnect

TonCenter API Keys

Built-in mainnet/testnet requests read TONCENTER_MAINNET_API_KEY or TONCENTER_TESTNET_API_KEY, depending on the selected network.

For custom:<name>, Acton reads <NORMALIZED_NAME>_API_KEY. Custom network names are uppercased and non-alphanumeric characters are replaced with _, so custom:mock-remote becomes MOCK_REMOTE_API_KEY.

Acton loads .env automatically, so the simplest setup during project work is usually to keep these keys there and use shell environment variables only for one-off overrides or CI.

See Also

Last updated on

acton check

Reference manual for the acton check command

acton fmt

Reference manual for the acton fmt command

On this page

Synopsis
Description
Options
Script Options
Debugging Options
Cache Options
Remote Options
Broadcasting Options
Output Options
Display Options
Project Options
Script Model
Argument Forwarding
Script Arguments
Side Effects
Exit Status
Safe Execution Order
Examples
TonCenter API Keys
See Also