> ## 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:remove_file

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

export const Ecosystem = () => <CardGroup cols={3}>
    <Card title="Documentation" icon="book" href="/introduction">
      Guides, reference contracts and working examples.
    </Card>
    <Card title="Language spec" icon="file-contract" href="https://github.com/supernovae-st/nika-spec">
      the nine-key envelope, Apache-2.0. The contract these docs explain.
    </Card>
    <Card title="Engine source" icon="gem" href="https://github.com/supernovae-st/nika">
      Rust, AGPL-3.0-or-later. Every commit public.
    </Card>
    <Card title="TypeScript SDK" icon="code" href="/sdk/overview">
      Use one typed lifecycle locally or against authenticated nika serve HTTP.
    </Card>
    <Card title="Editor extension" icon="puzzle-piece" href="https://marketplace.visualstudio.com/items?itemName=supernovae.nika-lang">
      VS Code · Cursor · Windsurf: check-as-you-type, DAG view, trace replay.
    </Card>
    <Card title="Homebrew tap" icon="beer-mug-empty" href="https://github.com/supernovae-st/homebrew-tap">
      `brew install supernovae-st/tap/nika` for the latest tagged CLI release.
    </Card>
    <Card title="SuperNovae" icon="star" href="https://supernovae.studio">
      The Paris studio crafting Nika. 🦋
    </Card>
  </CardGroup>;

[Builtins catalog](/reference/builtins) / `nika:remove_file`

<CardGroup cols={2}>
  <Card title="File" icon="layer-group">Tool family from the canonical registry.</Card>
  <Card title="invoke" icon="code" href="/reference/language/words/invoke">Call this builtin through the invoke verb.</Card>
</CardGroup>

## 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](/reference/status) 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:remove_file", args: { path: "./out/scratch.txt" } }
```

Remove ONE existing regular file named by `path:` · returns the requested
path string. The arguments are exactly `{ path: string }`: there is no
recursive, glob, force, missing-ok or destination option, no alias and no
`nika:delete`.

**Authority.** Removal is an external filesystem **write** effect. It needs
the callable's tool grant (`permits.tools`) AND a `permits.fs.write` bound
containing the exact resolved path. It needs no read grant: no content is
read, and no parent directory is created. A preceding copy (`nika:read` →
`nika:write`) needs its own independent read and write grants. Removal joins
the ordinary authority, taint, consent and composition laws exactly like
`nika:write`, and the same-path mutation law (`NIKA-SEC-012`): ordered
mutations of one path are permitted; an incomparable write/remove or
remove/remove pair on one path, or a `for_each` fan onto one constant path,
is refused. There is no global one-writer rule.

**Path shape** (judged on the RAW spelling, before any normalization). The
components are delimited by `/` and the target platform's main separator.
The path MUST be a non-empty string; it is not trimmed (a single-space file
name is a name). A trailing separator, a final `.` or `..` component, or a
root or platform prefix with no file name names a directory and is refused —
`out/.` is refused even though a pure path API normalizes the final dot
away. On POSIX a backslash is an ordinary file-name character, never
silently turned into a separator. `out/./note`, `out/part/../note`,
`out/...` and ` ` pass the shape rule; the boundary judges them next.
Wildcard-looking characters (`*` · `?` · `[`) are literal file-name
characters: one path names one target and is never expanded.

**Execution.** The engine validates, without following links, that an
existing **regular** entry sits at the resolved path. A missing entry, a
directory, a symlink (dangling or not), a FIFO or any other special entry
fails; there is no recursive removal, no content-opening probe and no
link-following metadata fallback. Confinement to the granted boundary is
descriptor-relative or carries an equivalent guarantee; a backend that cannot
provide it refuses. Success reports the requested path only after the backend
reports the removal. That returned path, or a permit allow, is not
independent proof of disk state. No atomic inode comparison is promised: the
leaf may change between validation and unlink, but a substituted symlink
never redirects the removal to its target.

**Not a transaction.** Copy-then-remove is two effects. A failed publication
prevents a dependent removal; a removal that fails after a successful
publication leaves a visible copy. There is no rollback, inode-preserving
rename, whole-batch atomicity or automatic cleanup, and a cancellation
without a settled backend result does not prove that nothing was removed.

| Condition | Code | Category · transient |
| - | - | - |
| invalid argument object, keys or types, or an invalid **literal** path shape | `NIKA-BUILTIN-001` | `validation_error` · false |
| invalid resolved args or path shape | `NIKA-BUILTIN-REMOVE_FILE-001` | `validation_error` · false |
| the permitted operation fails: absent or nonregular entry, unsupported backend, ordinary OS error | `NIKA-BUILTIN-REMOVE_FILE-002` | `tool_error` · false |
| tool grant or write boundary escaped | `NIKA-SEC-004` | `security_error` · false |
| the whole `permits:` block absent | `NIKA-AUTH-006` | `security_error` · false |
| a statically resolved untrusted value escapes | `NIKA-AUTH-008` | `security_error` · false |
| unordered shared mutation or constant-target fan | `NIKA-SEC-012` | `security_error` · false |

The static path-shape judgment covers literal paths only. The shape of a
templated path string is deferred whole to the judgment of its resolved
value, even when a trailing `/` or a final `/.` is visible in the template
(`REMOVE_FILE-001` then refuses it); deferral never means the path is safe
or runnable. A missing or non-string `path`, a non-object `args` and any
extra argument key stay static refusals, even beside a templated path.

An authority refusal is never reported as `REMOVE_FILE-002`.

## Related concepts

<CardGroup cols={2}>
  <Card title="Arguments" icon="sliders" href="/reference/language/words/args">Pass the values required by the tool contract.</Card>
  <Card title="Permissions" icon="shield" href="/concepts/security">Understand authority before granting effects.</Card>
  <Card title="Errors and recovery" icon="rotate" href="/reference/error-codes">Read diagnostics and choose a recovery policy.</Card>
  <Card title="Workflow templates" icon="file-code" href="/guides/templates">Put the fragment inside a complete workflow.</Card>
</CardGroup>

## Contract provenance

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

Tool identity: `nika:remove_file`. Specification revision: `480f5b80cb77`.

<Ecosystem />


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