> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nika.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# nika:write

> Usage, declared contract and source links for this Nika builtin.

[Builtins catalog](https://docs.nika.sh/reference/builtins.md) / `nika:write`

> [card] File
>
> Tool family from the canonical registry.

> [card] [invoke](https://docs.nika.sh/reference/language/words/invoke.md)
>
> 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](https://docs.nika.sh/reference/status.md) and `nika catalog --tools --json` for the installed implementation; a registry declaration is not a runtime qualification.

## Usage and behavior

```yaml illustration theme={"system"}
invoke: { tool: "nika:write", args: { path: "./out.md", content: "...", create_dirs: true, overwrite: true } }
```

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`.

## Related concepts

> [card] [Arguments](https://docs.nika.sh/reference/language/words/args.md)
>
> Pass the values required by the tool contract.

> [card] [Permissions](https://docs.nika.sh/concepts/security.md)
>
> Understand authority before granting effects.

> [card] [Errors and recovery](https://docs.nika.sh/reference/error-codes.md)
>
> Read diagnostics and choose a recovery policy.

> [card] [Workflow templates](https://docs.nika.sh/guides/templates.md)
>
> Put the fragment inside a complete workflow.

## Contract provenance

[Read the pinned specification](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/stdlib/builtins-v0.1.md#L173) · [Canonical registry](https://github.com/supernovae-st/nika-spec/blob/5cd95cd25c0ff453be266794a03666e5e3f2d7a8/canon/builtins.yaml).

Tool identity: `nika:write`. Specification revision: `5cd95cd25c0f`.

> [card] [Documentation](https://docs.nika.sh/introduction.md)
>
> Guides, reference contracts and working examples.

> [card] [Language spec](https://github.com/supernovae-st/nika-spec)
>
> the nine-key envelope, Apache-2.0. The contract these docs explain.

> [card] [Engine source](https://github.com/supernovae-st/nika)
>
> Rust, AGPL-3.0-or-later. Every commit public.

> [card] [TypeScript SDK](https://docs.nika.sh/sdk/overview.md)
>
> Use one typed lifecycle locally or against authenticated nika serve HTTP.

> [card] [Editor extension](https://marketplace.visualstudio.com/items?itemName=supernovae.nika)
>
> The editor extension, frozen at 0.120 and not qualified with 0.124: use `nika lsp` and the JSON Schema.

> [card] [Homebrew tap](https://github.com/supernovae-st/homebrew-tap)
>
> `brew install supernovae-st/tap/nika` for the latest tagged CLI release.

> [card] [SuperNovae](https://supernovae.studio)
>
> The Paris studio crafting Nika. 🦋


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.