add

Arguments and rejection

topaz add <name>@<version> declares one exact registry version. topaz add <name> --path <relative-path> declares one local package. A local declaration rejects an operand containing @.

A dependency name is a nonempty sequence of ASCII letters, digits, underscores, or hyphens. A version is a nonempty exact identifier using ASCII letters, digits, dots, underscores, hyphens, or plus signs. Version ranges are rejected.

A local path is nonempty and relative to the selected package root. The referenced package must load successfully and its declared package name must match the operand. Parent-relative local paths retain their filesystem meaning.

--root <dir> defaults to the current directory. The root must contain a valid topaz.toml. The manifest selects the language mode, so --language-version is rejected.

The name std is managed by the package language mode and cannot be added. A dependency that already exists is rejected even when the requested declaration is equal. Extra operands, --release, output-format options, missing values, repeated options, and attached values are rejected.

Output

On success standard output is empty and standard error identifies the added dependency and the updated manifest path.

Failures write a human diagnostic to standard error. --format json is rejected because dependency editing has no JSON report.

A registry declaration is emitted as a dependency table with a version member. A local declaration is emitted as a table with path and the computed content hash.

Exit status

Exit code 0 means the new manifest was validated and written.

Exit code 1 covers invalid arguments, invalid manifests, duplicate or reserved names, invalid versions or paths, local package identity mismatches, failed content hashing, and failed manifest writes.

Filesystem effects

The command reads the root manifest and reads local dependency content when --path is present. It writes the root topaz.toml after validating the complete proposed manifest.

The new declaration is appended to [dependencies]. The section is created when absent. Existing declarations and other sections retain their order. The resulting text uses line feeds and ends with a line feed.

The command does not change dependency source files. A write failure is an error and may leave a partial manifest because manifest replacement is not a multi-file transaction.

Network access

The command makes no network requests. Declaring a registry version neither downloads it nor verifies remote availability.

Reproducibility

For the same initial manifest bytes, operand, relative path, and admitted dependency bytes, the resulting manifest bytes are identical. Filesystem timestamps do not select a dependency version or content identity.

Repeating the same command against its completed result fails as a duplicate declaration.

Packages and locks

The command changes the manifest without updating or deleting topaz.lock and without materializing a vendor tree. An existing lock therefore becomes stale when its manifest identity changes.

A later lock or vendor operation records the new package identity. A locked compilation rejects the stale lock until it is updated.

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