init

Arguments and rejection

topaz init accepts no positional operands. --root <dir> selects the destination and defaults to the current directory. A supplied directory value must be nonempty.

The target is native. --target native selects it explicitly. Other target values are rejected before files are written.

The generated package uses the current language mode. An explicit --language-version must select that mode. It does not request an older scaffold.

Missing option values, unknown options, repeated options, attached values, program arguments after --, and output-format options are rejected before package creation.

Output

Successful creation leaves standard output empty. Standard error reports the package name and resolved destination in one completion line.

Failures write a human diagnostic to standard error and leave standard output empty. --format json is rejected because initialization has no JSON report.

The generated manifest has package version 0.1.0, entry src/main.tpz, native build target, deterministic builds enabled, and a std dependency table containing the current language version. The entry is a complete Topaz program that writes Hello from Topaz and returns success.

Exit status

Exit code 0 means both the manifest and entry were written completely.

Exit code 1 covers invalid arguments, an unsupported target or language mode, an existing destination file, an unreadable destination, and any directory or file write failure.

Filesystem effects

The command creates the selected root and its src directory as needed. It creates topaz.toml and src/main.tpz with exclusive file creation.

Both destination paths are checked before either file is written. An existing manifest or entry is an error even when its contents match the scaffold. Other files in the root are preserved.

The manifest is written before the entry. A later I/O failure can leave the new manifest and directories behind. A failed scaffold is incomplete and is never reported as successful.

Network access

Initialization uses the installed template and makes no network requests. It does not download the standard library or a toolchain.

Reproducibility

The same installed release, current language mode, and destination basename produce the same scaffold bytes. The package name keeps ASCII letters, digits, underscores, and hyphens from the basename and replaces other characters with underscores. An absent or empty basename selects topaz_app.

The destination path in the completion message is resolved for the current filesystem. Repeating initialization in an already populated destination fails instead of replacing it.

Packages and locks

The standard-library dependency uses a table as required by dependency-table.1. Initialization creates neither topaz.lock nor a vendor tree. Lock generation is a separate operation.

The invocation topaz init main.tpz --language-version 5.21 is expected to exit with 1.