acton fmt

Description

Format .tolk files using the built-in Tolk formatter.

The command can rewrite files in place or run in --check mode for CI and pre-commit validation. If no _paths_ are provided, Acton scans the resolved project root recursively.

For editor integrations, acton fmt --stdin reads one Tolk source buffer from standard input and writes only the formatted source to standard output.

Options

Format Options

<paths>...

Files or directories to format.

If omitted:

Acton scans the project root.

Conflicts with:

--stdin

Repeatable:

May be passed multiple times.

--check

Check formatting without rewriting files.

In this mode Acton prints diffs for mismatches and exits non-zero.

--stdin

Read Tolk source from standard input and write formatted source to standard output.

This mode is intended for editor and IDE integrations. It does not rewrite files and, unless combined with --check, does not print status messages to standard output.

Conflicts with:

paths

--stdin-filepath<PATH>

Virtual file path to use for diagnostics when formatting source from standard input.

This option is accepted only with --stdin. Acton does not read or write this path.

--range<startLine:startChar-endLine:endChar>

Format only the specified zero-based source range.

This is intended for editor integrations that format a selected region. Lines are zero-based, and startChar / endChar are zero-based UTF-8 byte columns. Editor integrations that expose Unicode scalar or UTF-16 positions need to convert them before invoking Acton.

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

Behavior

Only .tolk files are formatted
Directory traversal is recursive
Built-in ignore globs always apply, including node_modules, .git, target, and .acton
explicit file arguments are formatted even if they would match [fmt].ignore
directory traversal applies [fmt].ignore and built-in excludes to relative and absolute paths
Syntax errors are reported as diagnostics and cause a non-zero exit
--check prints a unified diff with three lines of context for each changed file
--stdin writes only formatted source to stdout; diagnostics and errors go to stderr
--stdin --check compares stdin with formatted output and prints a unified diff if formatting would change
--range keeps nodes outside the specified range unchanged and disables import reordering for that invocation
--range can only be used with one explicit .tolk file path, unless --stdin is used

Configuration

acton fmt reads defaults from [fmt] in Acton.toml:

Acton.toml

[fmt]
width = 100
ignore = ["contracts/generated/*.tolk"]
separate-import-groups = true

Useful fields include:

width for maximum formatted line width
ignore for additional exclude globs
separate-import-groups for blank lines between import groups

Import Sorting

Imports are sorted by group in this order:

@stdlib
@acton
other @... imports
plain imports
./...
../...

Within each group, imports are sorted lexicographically.

Exit Status

0: All requested files were formatted successfully, or --check found no formatting differences.
1: Files needed formatting in --check mode, syntax errors prevented formatting, or path resolution failed.

Examples

Format all Tolk files in the project:
```
acton fmt
```
Format selected paths:
```
acton fmt contracts scripts/deploy.tolk
```
Validate formatting without writing files:
```
acton fmt --check
```

Run against another project root:

acton --project-root ../my-project fmt --check

Check import grouping after enabling blank lines between groups:
```
acton fmt contracts/main.tolk --check
```

Format only a selected source range:

acton fmt contracts/main.tolk --range 2:4-5:1

Format an editor buffer through stdin/stdout:

acton fmt --stdin --stdin-filepath contracts/main.tolk < contracts/main.tolk

acton fmt

Synopsis

Description

Options

Format Options

Display Options

Project Options

Behavior

Configuration

Import Sorting

Exit Status

Examples

See Also

On this page