acton init

Synopsis

acton init [options]

Description

Initialize Acton support in the current working directory.

By default, this command is intended for existing repositories or ad-hoc directories where you want to add Acton.toml, standard Acton ignore rules, the bundled standard library, and symlinks to global wallet and library overlays.

If Acton.toml already exists, acton init leaves it untouched.

If Acton.toml does not exist, the command scans .tolk files in the current directory tree and auto-registers files that define onInternalMessage as contract entry files.

With --create-dapp, acton init switches to app-only mode. In that mode, Acton does not create or patch Acton.toml, .gitignore, .acton/, or overlay symlinks. It only creates a Vite-based TypeScript app scaffold in ./app by default, or in the provided path.

With --stdlib-only, acton init switches to standard-library-only mode. In that mode, Acton does not read, create, or patch Acton.toml, does not patch .gitignore, and does not create overlay symlinks. It re-extracts the bundled standard library into .acton/ even when Acton.toml is missing or the stored stdlib version already matches the current Acton version.

Idempotency

acton init is safe to run repeatedly.

• it does not read, delete, recreate, or rewrite an existing Acton.toml
• it appends missing .gitignore patterns without deleting existing ones
• it refreshes .acton/tolk-stdlib
• it re-attempts global wallet and library symlinks on each run

The --create-dapp mode is not idempotent: it fails if the target app directory already exists.

The --stdlib-only mode is safe to run repeatedly, but it always re-extracts the bundled standard library instead of relying on the stored version marker.

Init Options

Display Options

Project Options

Generated And Patched Files

The default acton init flow can create or update:

• Acton.toml
• .gitignore
• .acton/
• local symlinks for global.wallets.toml and global.libraries.toml

With --create-dapp, acton init only creates app/ or the provided app directory.

With --stdlib-only, acton init only creates or updates .acton/.

When Acton.toml is created from scratch, it starts from Acton's default project config and may include:

• [package] metadata
• [fmt] defaults
• discovered [contracts]
• default [import-mappings]

When Acton.toml already exists, acton init skips project configuration and does not read or rewrite the manifest.

When patching .gitignore, Acton adds groups for:

• Acton artifacts such as .acton/, gen/, build/, and lcov.info
• local and global wallet/library overlay files
• .env and mnemonic files

Contract Discovery

When generating a new Acton.toml, contract discovery:

• walks the current directory recursively
• skips hidden directories and entries such as node_modules, target, .git, and .acton
• considers .tolk files only
• treats files with an onInternalMessage function as contract entry files
• derives the contract key from the file stem with - normalized to _
• derives the default display name from the file stem by splitting on _ and -, then capitalizing each word

Standard Library

acton init ensures that the bundled Tolk standard library is installed into .acton/tolk-stdlib.

With --stdlib-only, Acton refreshes the bundled standard library unconditionally and does not require Acton.toml to exist.

If global wallet or library overlay files already exist, acton init also tries to create local symlinks for them. Existing local files and non-dangling symlinks are left in place; Acton only creates the link when the local path does not already resolve. If the local path is a dangling symlink, Acton still attempts link creation because the path looks missing, but that attempt currently warns instead of repairing the dangling link.

If symlinks for global wallets or libraries cannot be created, Acton prints a warning and still completes initialization. This is relevant on systems where symlink creation is restricted.

Side Effects

The default acton init flow writes or patches local project files and may create local symlinks to global overlay files. It does not modify Git config. If Acton.toml already exists, Acton leaves it untouched; .gitignore patching remains append-only.

The default flow normally refreshes the bundled standard library under .acton/. Set ACTON_DISABLE_AUTO_STDLIB=1 to skip that automatic refresh. This does not affect --stdlib-only, which always refreshes .acton/ explicitly.

With --create-dapp, acton init writes only inside the new app directory and does not touch Acton project files.

With --stdlib-only, acton init writes only inside .acton/.

Exit Status

• 0: Initialization completed successfully, including no-op repeat runs.
• 1: Manifest parsing, stdlib installation, writing or patching project files, or another hard filesystem operation failed. Contract discovery skips unreadable/unparseable .tolk files, and overlay symlink failures only warn. In --stdlib-only mode, manifest parsing and overlay symlink operations are skipped.

Examples

1. Initialize Acton support in an existing repository:

   acton init

2. Refresh support files in a project that already has Acton.toml:

   acton init

3. Create only the default app scaffold:

   acton init --create-dapp

4. Create only the app scaffold in frontend/:

   acton init --create-dapp frontend

5. Re-run safely after .acton/ or .gitignore need refresh:

   acton init

6. Refresh only the bundled standard library:

   acton init --stdlib-only

See Also

• acton help new
• acton help doctor
• Project management guide