Acton TON CLI Workflow

Source of truth

• Prefer the exact installed binary for command spelling and behavior:

- acton --version - acton --help - acton help <command> - acton <command> --help

• Use official hosted docs for current concepts, tutorials, and full reference:

- https://ton-blockchain.github.io/acton/docs/welcome/ - https://ton-blockchain.github.io/acton/docs/commands/ - https://ton-blockchain.github.io/acton/llms-full.txt

• Use the official examples repo for real project patterns and reference contracts:

- https://github.com/ton-blockchain/acton-contracts

• Read bundled references only when needed:

- references/command-map.md for fast command selection - references/troubleshooting.md for common failure modes

• Do not assume local paths, private checkouts, or a specific developer machine.
• Use GitHub source only when the user explicitly asks to inspect upstream implementation. Treat acton-contracts as examples of project structure and contract patterns, not as the source of truth for CLI flags.
• If docs and the installed CLI disagree, state the Acton version and follow the installed CLI for that local workflow. If the user wants latest behavior, suggest acton up or the install/update flow first.

First-release exclusions

• Do not recommend acton localnet or --net localnet. That feature may remain visible in source or trunk help, but it is excluded from the first release and should be treated as unavailable in public workflows.

Install or update Acton

If acton is missing and the task requires running it, install the public binary:

curl -LsSf https://github.com/ton-blockchain/acton/releases/latest/download/acton-installer.sh | sh

Then open a fresh shell or reload the updated shell profile if needed, and verify:

acton --version
acton --help

Update and version management:

• acton up installs the latest stable release.
• acton up --list lists available versions.
• acton up <version> installs a specific version.
• acton up --trunk installs the latest trunk build when supported by the installed CLI.
• In CI, prefer ton-blockchain/setup-acton@master or the published ghcr.io/ton-blockchain/acton:<version> image.

First checks in any project

1. Confirm tool and project context:

- acton --version - acton doctor - pwd

1. If running from outside the project, select context explicitly:

- acton --project-root <PATH> ... - acton --manifest-path <PATH>/Acton.toml ...

1. Inspect the relevant command help before relying on memory:

- acton help build - acton help test - acton help script

1. Inspect Acton.toml for the sections that matter:

- [package] - [contracts] - [build] - [wrappers.tolk] - [wrappers.typescript] - [fmt] - [test] - [lint] - [networks] - [scripts] - [import-mappings]

Project-root rule: config-relative paths are resolved from the project root. Relative CLI path flags are resolved from the current working directory unless passed as absolute paths.

Project bootstrap

• Use acton new [path] --template empty|counter|jetton|nft for a fresh project.
• Useful acton new flags:

- --name, --description, --license - --app for the TypeScript/Vite app scaffold when the template supports it - --hooks for default project Git hooks - --agents for generated coding-agent guidance

• Use acton init to add Acton support to an existing directory.
• Useful acton init modes:

- acton init --create-app [path] creates only the TypeScript app scaffold - acton init --stdlib-only refreshes only the bundled standard library

• acton init can patch default [import-mappings] into an existing manifest, but that rewrite may drop TOML comments and unknown keys.

Build, compile, and wrappers

• acton build [contract-name]

- Builds all contracts, or one contract plus transitive dependencies. - Common flags: --clear-cache, --graph <path>, --out-dir <dir>, --gen-dir <dir>, --output-fift <dir>, --info.

• acton compile <file.tolk>

- Single-file compiler entrypoint. - Common flags: --json, --base64-only, --boc <file>, --fift <file>, --source-map <file>, --abi <file>, --allow-no-entrypoint, --clear-cache.

• acton wrapper <contract-name>

- Generates Tolk wrappers from contract ABI. - Use --test, --test-output, or --test-output-dir for test stubs. - Use --ts for TypeScript wrappers via gen-typescript-from-tolk. - Do not combine --ts with test-stub generation.

• If ABI, storage, or message types changed, regenerate wrappers instead of hand-editing generated files.
• Wrapper output defaults come from [wrappers.tolk], [wrappers.typescript], and the @wrappers import mapping.

Tests and quality gates

• Core entrypoint: acton test [path].
• Common test flags:

- --filter <regex>, --include <glob>, --exclude <glob> - --fail-fast - --fuzz-seed <seed> - --verbose for low-level executor logs - --debug --debug-port <port> - --backtrace full - --reporter console|dot|teamcity|junit or comma-separated combinations - --junit-path <dir>, --junit-merge - --show-bodies - --clear-cache

• Coverage:

- acton test --coverage --coverage-format lcov - acton test --coverage --coverage-format text - --coverage-file <path> - --coverage-minimum-percent <percent> - --coverage-include-wrappers - --coverage-include-tests

• Gas profiling:

- acton test --snapshot build/gas-baseline.json - acton test --baseline-snapshot build/gas-baseline.json - acton test --baseline-snapshot build/gas-baseline.json --fail-on-diff

• Mutation testing:

- acton test --mutate --mutate-contract <contract-name> - --mutation-diff worktree|ref|branch - --mutation-diff-ref <ref> - --mutation-levels critical,major,minor - --mutation-disable-rules <rule> - --mutation-rules-file <path> - --mutation-session-id <id> - --mutation-id <id> - --mutation-workers <n> - --mutation-minimum-percent <percent>

• Fork tests:

- acton test --fork-net testnet|mainnet|custom:<name> - acton test --fork-net testnet --fork-block-number <seqno>

• Test UI and traces:

- acton test --ui - acton test --ui --ui-port <port> - acton test --save-test-trace - acton test --save-test-trace <dir>

• Defaults live in [test], [test.coverage], [test.fuzz], and [test.mutation]. CLI flags override config for the current run.

Linting, formatting, and hooks

• acton check [target]

- Checks a project, contract name, or .tolk file. - Common flags: --fix, --output-format plain|json|sarif|github|gitlab, --output-file <path>, --enable-only <code[,code...]>, --explain <rule>.

• Lint config lives in [lint], [lint.rules], and [lint.rules.<contract-name>].
• Inline suppressions use // check-disable-next-line ....
• acton fmt [paths...]

- Formats sources. - Use acton fmt --check in CI. - Defaults live in [fmt].

• acton hooks new|install|status|uninstall

- Manages project-local Git hooks under .githooks.

• Typical CI gates:

- acton build - acton test --reporter console,junit - acton check --output-format github - acton fmt --check

Scripts, deployment, and network reads

• acton script <path> [args...] runs a standalone Tolk script.
• There is no acton deploy command. Deployment is script-driven.
• Safe execution sequence for state-changing scripts:

1. acton build 2. acton test 3. acton script <path> to emulate locally 4. acton script <path> --net testnet 5. only after testnet validation, acton script <path> --net mainnet

• --net <network> broadcasts real transactions to testnet, mainnet, or custom:<name>. If --net is omitted, execution stays local.
• --fork-net <network> reads remote state while executing locally. When --net is set, omitted --fork-net defaults to the selected network for reads.
• Common script flags: --debug, --debug-port, --backtrace full, --verbose, --clear-cache, --fork-net, --fork-block-number, --net, --explorer tonscan|toncx|dton|tonviewer, --show-bodies.
• acton run <script-name> [args...] runs entries from [scripts] in Acton.toml.
• Script arguments are parsed against main() ABI. Use -- before forwarded args that look like Acton flags.
• Built-in network API keys are environment variables, usually loaded from .env:

- TONCENTERTESTNETAPIKEY - TONCENTERMAINNETAPIKEY - <NORMALIZEDNAME>API_KEY for custom:<name>

Wallets, verification, and inspection

• Wallets:

- acton wallet new - acton wallet import - acton wallet list - acton wallet export-mnemonic - acton wallet sign - acton wallet remove - acton wallet airdrop

• Prefer secure keyring storage when available. Use mnemonic-env for CI and never commit plaintext wallet files or mnemonics.
• Verification:

- acton verify [contract-name] --address <addr> --net testnet|mainnet - Useful flags: --wallet <name>, --compiler-version <version>, --dry-run.

• RPC inspection:

- acton rpc info <address> - acton rpc block - acton rpc block-number - acton rpc trace <hash>

• On-chain libraries:

- acton library publish - acton library fetch - acton library info - acton library topup

• Low-level tools:

- acton disasm [boc-file] - acton retrace <tx-hash> - acton doc tvm <query...> - acton func2tolk <path> - acton ls --stdio or acton ls --port <port> - acton completions bash|elvish|fish|powershell|zsh|nushell

Safety and correctness rules

• Warn once before acton script --net mainnet, acton verify, acton library publish, or acton library topup.
• State wallet, network, project-root, and Acton version assumptions explicitly when they affect the result.
• Do not invent commands or flags. Verify with acton help <command> when unsure.
• Do not use old examples with acton litenode, [mappings], --broadcast, --api-key, or acton up --canary unless the user's installed binary explicitly supports them.
• Use TON docs for blockchain concepts that Acton docs do not cover; use Acton docs for CLI behavior.