acton init

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 patches in default mappings when they are missing instead of creating a fresh scaffold. That patch path rewrites the parsed manifest, so TOML comments and unknown keys are not preserved.

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 delete and recreate an existing Acton.toml, but it may rewrite the file when backfilling default mappings
it backfills default import-mappings only when they are missing
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

--create-dapp[<path>]

Create a Vite-based TypeScript app scaffold instead of performing project initialization.

If _path_ is omitted, Acton uses app. The target directory must not already exist.

--stdlib-only

Update the bundled standard library without touching Acton.toml.

This mode always re-extracts the standard library into .acton/, even outside an initialized Acton project.

Display Options

--color<when>

Control when to use colored output.

Possible values:

auto, always, never

Project Options

--manifest-path<path>

Pass-through:

Accepted as a global Acton option for CLI consistency.

This command does not require an existing project manifest for its primary workflow. It remains mutually exclusive with --project-root.

--project-root<path>

Pass-through:

Accepted as a global Acton option for CLI consistency.

This command does not require an existing project root for its primary workflow. It remains mutually exclusive with --manifest-path.

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 only backfills missing default [import-mappings] entries. This patch path reloads the file into Acton's typed config and writes it back out, so comments and unknown keys are dropped.

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. When it patches an existing Acton.toml, it rewrites the parsed manifest and may drop TOML comments or unknown keys; .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

Initialize Acton support in an existing repository:
```
acton init
```
Regenerate default mappings in an existing Acton.toml:
```
acton init
```
Create only the default app scaffold:
```
acton init --create-dapp
```
Create only the app scaffold in frontend/:
```
acton init --create-dapp frontend
```
Re-run safely after adding more contracts:
```
acton init
```
Refresh only the bundled standard library:
```
acton init --stdlib-only
```