# Using niv from an agent

An agent (Claude Code, Codex or any other) can drive `niv` the way a script does: name the folder, read JSON, check the exit status, and never wait on a question. These are the rules that keep it safe. This page describes niv 0.2.25.

## Give it the rules

`niv skill` (niv 0.2.14 and later) prints a skill file written for the niv you have installed. Save it where your agent reads skills:

```
mkdir -p .claude/skills/niv && niv skill > .claude/skills/niv/SKILL.md
```

For every project, save it in `~/.claude/skills/niv/SKILL.md` instead. Run it again after you update niv, so the skill matches the version.

## The rules

1. **Name the folder.** Pass `--folder <path>` on every command, or set `NIV_FOLDER` once. Don't rely on the working directory.
2. **Ask for JSON.** Add `--json`, parse stdout (one object per command, one event per line for `niv sync`), and branch on `code`, never on the sentence. See [Output for scripts](/p/docs/output-for-scripts).
3. **Check the exit status.** 0 is done; anything else has a meaning. See [Exit codes](/p/docs/exit-codes).
4. **Nothing asks.** Without a terminal, niv never waits for an answer. Where a flag answers the question, it stops with exit 2 and names it (`--yes`, `--space`, `--address`). A missing key passphrase is exit 3 (`key-no-terminal`): give it in `NIV_KEY_PASSPHRASE_FILE`. `niv sign-in` needs a person at a terminal.
5. **Sync to a known point, with a limit.** `niv sync --once --timeout 5m` returns when the folder and the Space match (0), or why they can't yet (1, 3, 4, 5). At the limit it exits 1 with code `timeout`. In an encrypted Space, the first run after niv is updated reads every note once and takes longer; code `catching-up` (exit 1) means run it again, and it goes on from where it stopped. A wrong command is 2, a refusal 6 (such as a folder an older Niv app syncs), and ctrl+c 130.
6. **Holds are a person's call.** When `--once` exits 1 on a hold, read `niv holds --json` and tell the person what waits. The list is as of the last sync (`asOf`), so read it after a `--once`. Choose for them only what they asked you to, and never `--deleted` on a guess: `--keep-both` loses nothing.
7. **Look before publishing.** `niv publish <folder> --dry-run --json` first. A page is public to anyone with its address. Use `--except` for what must stay private.
8. **Keep secrets off the command line.** The key file's passphrase goes in `NIV_KEY_PASSPHRASE_FILE`, never in an argument. See [Sign in and keys](/p/docs/sign-in-and-keys).
9. **Look it up offline.** `niv help <command>`, `niv help json` and `niv help environment` match the installed version exactly.

## Edit notes as files

Notes are Markdown files in the folder. Edit them with your usual tools; a running `niv sync` sends each change. Without a running sync, run `niv sync --once` after editing.

- A new note is a new `.md` file: sync reports it as `sent` with `new: true`.
- Move and rename files while sync runs, even as it starts, so niv follows them as the same notes. A file moved while nothing ran is followed when its content is unchanged; moved and edited, its old path becomes a hold: answer it with `--moved-to <path>`.
- Delete a file while sync runs and its note goes to the Space's trash: `trashed`, then `removed`. A folder deleted while sync runs goes for everyone too, after its notes: `trashed Ideas/`. A file deleted while nothing ran waits as a hold instead, and so do ten or more deleted as sync starts.
- Many new files at once wait for a look as a whole-folder hold (`.`): `niv holds . --show --json` lists them, and `--sync-now` lets them in.
- If another device deletes a note you edited, your edit comes back as a `(copy)` note, reported as `moved` with `reason: "deleted-elsewhere"`. Tell the person.
- If the person, or another folder, edits the same note while you do, both edits are merged, even within a line, with no hold and no line from niv. The Niv app marks the paragraph when both syncs were running; an edit you made while no sync ran is marked only in an encrypted Space. Read the note again after `--once` before you build on it. See [Keep a folder in sync](/p/docs/keep-a-folder-in-sync).
- Files listed as local only never leave the computer.

## A session

```
export NIV_FOLDER=~/notes
niv status --json                          # connected? anything on hold?
niv status "Weekly report" --json          # is this one note synced?
niv sync --once --timeout 5m --json        # catch up first
# … edit notes as files …
niv sync --once --timeout 5m --json        # send the edits
niv holds --json                           # anything to tell the person?
niv publish "Weekly report" --dry-run --json
niv publish "Weekly report" --yes --json
```

## Databases and MCP

A Space's databases aren't files: read and change them with [niv databases](/p/docs/niv-databases). An app that speaks MCP can start niv itself and use tools instead: see [niv mcp](/p/docs/niv-mcp).

## When the person uses the Niv app too

The app and niv never sync the same folder at once. While the app has the folder open, niv waits (`state: "observing"`) and `--once` exits 0: the app sends the edits. If the app has the folder but stopped syncing it, `--once` exits 1 (code `observing`); an older app that doesn't tell niv it has the folder gets exit 6 (`synced-by-app`). See [Your agent in the terminal](/p/docs/your-agent-in-the-terminal) for working on a folder the app keeps in sync.

---

Published with [Niv](https://niv.md/) in the Space Docs.
