Skip to main content
Builtins catalog / nika:write

File

Tool family from the canonical registry.

invoke

Call this builtin through the invoke verb.

​
Read this contract

This reference preserves the specification at the revision linked below. Source examples are fragments: their surrounding tasks, inputs and permissions are not supplied here. Consult engine status and nika catalog --tools --json for the installed implementation; a registry declaration is not a runtime qualification.

​
Usage and behavior

illustration
Write a file · path: names a FILE, never a directory · returns the path. A binary content value (an opaque bytes output from an upstream tool · e.g. MCP image content) is written as-is · no output_format declaration needed (the value carries its own type). A directory is never the target: it is made by writing its first file inside it with create_dirs: true, never by an empty write at the directory’s path. content: strings are written verbatim. Numbers, booleans, arrays and ordinary objects are written as compact JSON, with no added newline. An object containing a bytes_base64 key is treated as binary: that value must be a valid base64 string, it is decoded to bytes, and the other keys are ignored; an invalid value is refused with NIKA-BUILTIN-WRITE-001. The file extension does not select a serializer: an integer value 42 writes 42, an object { "sum": 42 } writes that object, and a string already containing JSON is not encoded a second time. The reference engine serializes object keys in sorted order, including nested objects; field order in a constructed JSON object does not promise byte order in the file. A value computed as a floating-point number retains its float form (3.0, 100.0, or 0.30000000000000004): writing adds no decimal rounding or arithmetic exactness. A string built by the program retains its own byte order and number text. A present null content: is refused with NIKA-BUILTIN-WRITE-001; pass the string "null" to write that literal text. In a checked workflow, an absent required content: argument is refused by check with NIKA-BUILTIN-001; a reference to a missing upstream value fails before the write with NIKA-VAR-001. A direct builtin call without content: is also refused with NIKA-BUILTIN-WRITE-001. overwrite: defaults true · create_dirs: defaults false — and a false create_dirs: is ENFORCED, not ignored: a missing parent directory is refused loudly (a typo’d path surfaces rather than silently materializing a directory tree), so pass create_dirs: true to create the parent. One carve-out, by decision (engine #433 option C): a declared permits.fs.write entry covering the target path IS the intent — the boundary creates the parent tree before the builtin’s gate, and the write lands without create_dirs: (measured on the reference engine: a literal grant deep/dir/new.txt and a glob grant out/** both materialize their tree · run green). The refusal keeps its teeth where no declared grant covers the path — and there the boundary itself speaks first: an uncovered write is NIKA-SEC-004 before the parent gate can. A typo’d path under a narrow grant still surfaces (it falls outside the grant → SEC-004); the tree-scatter the enforcement exists to catch cannot hide inside a boundary the author drew. Throws · NIKA-BUILTIN-WRITE-001 (IO failure, or a missing parent while create_dirs: false outside a covering grant · a directory-shaped path: — a trailing / is write failed: path not found, an existing directory is filesystem I/O error: Is a directory · a file in the way of create_dirs: — create_dirs failed: path already exists, the mark an earlier empty write at the directory’s path leaves behind, which nika:write never removes; all three measured on the reference engine 0.118.7) · -002 (overwrite: false and the path exists). Both tool_error · transient: false.

Arguments

Pass the values required by the tool contract.

Permissions

Understand authority before granting effects.

Errors and recovery

Read diagnostics and choose a recovery policy.

Workflow templates

Put the fragment inside a complete workflow.

​
Contract provenance

Read the pinned specification · Canonical registry. Tool identity: nika:write. Specification revision: 5cd95cd25c0f.

Documentation

Guides, reference contracts and working examples.

Language spec

the nine-key envelope, Apache-2.0. The contract these docs explain.

Engine source

Rust, AGPL-3.0-or-later. Every commit public.

TypeScript SDK

Use one typed lifecycle locally or against authenticated nika serve HTTP.

Editor extension

The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema.

Homebrew tap

brew install supernovae-st/tap/nika for the latest tagged CLI release.

SuperNovae

The Paris studio crafting Nika. 🦋