UTTORI ASM · IN DEVELOPMENT

CLI paths and errors

Understand CLI path resolution, diagnostics, and failure behavior.

Valued options accept --flag value or --flag=value. Boolean flags take no value: omit them to disable them, so --force=false throws an error. Repeat --plugin, --include-path, --plugin-option, and --entry as needed, other repeated valued options use the last value. Unknown flags, flags for another command, missing values, invalid limits, and excess positional arguments fail before work. Use an explicit assemble if a source filename matches a command name.

Paths use the host OS's syntax. CLI input/output/config/base/ROM paths are relative to the current working directory. Plugin and include paths follow the configuration resolution rules. Quote paths containing spaces. Use -- to stop option parsing, for example uttori-asm assemble -- --source.asm output.bin. A valued option whose value begins with -- needs the equals form.

Normal success and --help return 0. Argument, input, configuration, compilation, verification, and cleanup failures return 1, with diagnostics on stderr. An analysis that records an explicit incomplete result returns 0. Inspect its status and reasons before treating discovery as complete. Help, progress, verbose details, and success messages use stdout. Warnings use stderr. Output is human-readable and has no uniform machine-readable schema. Use the exit status rather than matching a success line, since a later step or cleanup can fail.

Assembly replaces the chosen binary and optional debug map. Parent directories are created, both artifacts are computed and staged before publication, and each file is replaced by rename. Bad map paths or staging failures leave prior artifacts intact. Outputs must be distinct and cannot alias the entry source or selected config. An explicitly chosen base-image output can still patch that base in place. Choose a separate output to retain it. Publication is atomic per file, not across both files if termination or a rename error occurs between them.

The CLI installs no signal handlers and exposes no AbortSignal on runCli. Ctrl-C uses Node's default termination behavior (commonly shell status 130 on POSIX). It does not promise graceful cleanup or a returned API status. Before publication, interruption preserves the old assembly artifacts. A staged temporary sibling may remain. Hosts needing cooperative cancellation should use the underlying project APIs.