# Keep a folder in sync

Three ways to run sync: the live view to watch it, `niv sync` to leave it running, and `niv sync --once` to catch up and stop. `niv status` says how it's doing, or how one note stands, without starting anything.

## niv (the live view)

```
niv [--quiet] [--passphrase-file <path>] [--folder <path>]
```

Bare `niv` syncs the folder and shows it live: a header with the Space and the state, and a log of what arrives and leaves.

| Key       | Does                                           |
| --------- | ---------------------------------------------- |
| q, ctrl+c | Stop                                           |
| ↑ ↓, k j  | Move through the log                           |
| return    | Open a row's details, or a batch               |
| esc       | Close details, a batch, the filter or the help |
| h         | The holds screen, when something waits         |
| p         | Publish or update a note                       |
| /         | Filter the log                                 |
| ?         | All the keys                                   |

Without a terminal, bare `niv` prints plain lines, as `niv sync` does. With `--json` it never opens the live view: it prints the same events as `niv sync --json`.

To change how it looks: `NIV_THEME=dark` or `light` when niv guesses your terminal's background wrong, `NIV_MOTION=off` for no animation, `NIV_ASCII=1` for plain ASCII marks, and `NO_COLOR` (or `--no-color`) for no colour.

## niv sync

```
niv sync [--once [--timeout <time>]] [--json] [--quiet] [--folder <path>]
```

Keeps the folder in sync until it's stopped. Edits made here, by you, an editor or an agent, go to the Space, and edits from your other devices arrive here. One line per change:

```
$ niv sync --folder ~/"Field notes"
2026-10-29T03:02:06-03:00 state syncing
2026-10-29T03:02:07-03:00 sent Morning page.md new
2026-10-29T03:02:09-03:00 sent Unsent 01.md
2026-10-29T03:02:09-03:00 state synced
```

- `--once` syncs until the folder and the Space match, then exits: edits from your other devices have arrived, and the Space has confirmed this folder's edits.
- `--timeout <time>`, with `--once`: stop after this long, such as `30s`, `5m` or `1h`. At the limit it says so and exits with 1 (code `timeout`).
- `--json` prints one JSON object per line. See [Output for scripts](/p/docs/output-for-scripts).
- `--quiet` prints errors only. With `--json`, only `error` events.
- `--passphrase-file <path>`: a file that holds only the key file's passphrase. See [Sign in and keys](/p/docs/sign-in-and-keys).

ctrl+c stops it with exit 130; a `SIGTERM` from a service manager stops it with 0. Only one sync runs on a folder at a time: a second one says the folder is already syncing.

Delete a note's file while a sync runs and its note goes to the Space's trash. niv says so:

```
2026-10-29T16:00:14-03:00 trashed S1 dup.md
2026-10-29T16:00:33-03:00 removed 1 note was removed from Simple test because its file is no longer in this folder. It’s in the Space’s trash: you can restore it from the Niv app, in Settings › History, for 30 days.
```

The same goes from the moment `niv sync` starts, while it's still opening the folder. Only if ten or more notes go in those first seconds do they wait for you instead, and nothing is deleted until you answer.

Delete a folder while a sync runs, with its notes or after moving them out, and it goes from the Space too, for everyone: `trashed` for each note still in it, then `trashed Old ideas/`, the path ending in `/`. Every device then loses the folder, not just its notes, and says the same lines, the folder's last. An empty folder stays on your other devices if it never held a note here, or if its notes were moved out on another device.

A file deleted while nothing ran waits for you too, since niv can't tell a deletion from a mistake: see [Holds in the terminal](/p/docs/holds-in-the-terminal). A folder deleted while nothing ran asks about each of its notes. Answer each one `--deleted` and the next sync removes the folder for everyone too, with the same `trashed Old ideas/`.

### When --once exits

| Exit | When                                                                                                                                                                                                                                                                                                                                                                            |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0    | The folder and the Space match, or the Niv app is syncing the folder                                                                                                                                                                                                                                                                                                            |
| 1    | Something waits for you (see [Holds in the terminal](/p/docs/holds-in-the-terminal) and the note below), the `--timeout` came, sync stopped or couldn't start, another niv sync already runs on the folder, it stayed in a state such as `in-use`, `receive-only` or `connecting` for 2 minutes, or sending (or, in an encrypted Space, receiving) stopped moving for 2 minutes |
| 2    | A wrong command: an unknown option, a bad or lone `--timeout`, a file given as `--folder`                                                                                                                                                                                                                                                                                       |
| 3    | This computer is signed out, the key file can't be opened, or its passphrase is missing or wrong                                                                                                                                                                                                                                                                                |
| 4    | The folder isn't connected to a Space                                                                                                                                                                                                                                                                                                                                           |
| 5    | Niv can't reach its server                                                                                                                                                                                                                                                                                                                                                      |
| 6    | Refused: an older Niv app syncs the folder, or the folder is connected elsewhere                                                                                                                                                                                                                                                                                                |
| 130  | Stopped with ctrl+c (a `SIGTERM` gives 0)                                                                                                                                                                                                                                                                                                                                       |

In an encrypted Space, the first `--once` after you update niv reads every note once, so it takes longer: minutes on a large folder, with `progress` events in `--json`. Later runs read only the notes that changed. A read that keeps moving runs to its end; if it stops moving for 2 minutes, `--once` ends with code `catching-up` (exit 1) and says to run it again. What it read is kept, so the next run goes on from there.

Every hold gives exit 1 except a name Windows can't use, a file kept apart, or a file Niv can't read yet: `--once` can end with 0 while those wait, and `niv holds` lists them. A file another program has open counts only after the 2 minutes.

```
$ niv sync --once --folder ~/"Field notes"
2026-10-29T03:02:32-03:00 state divergence-held
Sync is waiting for a decision about 1 note. niv holds shows it.
$ echo $?
1
```

### On a server

Run `niv sync` as a service, with the key file's passphrase in `NIV_KEY_PASSPHRASE_FILE` or `--passphrase-file`. See [Sign in and keys](/p/docs/sign-in-and-keys).

## Moving and renaming files

Move or rename notes while a sync runs, from the moment it starts, and niv follows them as the same notes. A file moved while nothing ran is followed too, when its content is unchanged. One that was moved and also edited waits for you as a note whose file is gone, since niv can't be sure it's the same note: answer it with `--moved-to <path>`, or `--keep-both` if you're not sure. See [Holds in the terminal](/p/docs/holds-in-the-terminal). A note renamed on another device while you edited it here moves to its new name, with your edit.

niv tells each move once, as you made it, here and on your other devices: a note renamed and moved in one go is one line from where it was, such as `renamed Ideas/Plan final.md from Draft.md`, and a folder moved with its notes is one line for the folder, its path ending in `/`: `renamed Archive/Old ideas/ from Old ideas/`. With `--json` these are `moved` events, with `from`.

## Two edits to one line

Edit one note in two places at once (two folders, or a folder and the Niv app) and both edits are kept. They merge as in a shared document, even within a line: "The tide comes in late at noon." here and "The tide comes in at two." elsewhere become "The tide comes in late at two." Nothing waits, and niv prints nothing about it. When both edits are made while their syncs run, the Niv app marks the paragraph as edited in two places at once, in the note and in its History (see [Writing together](/p/docs/writing-together)). An edit made here while no sync ran, which `niv sync --once` sends after it takes in the other one, gets that mark only in an encrypted Space; in a plaintext Space it merges with no mark. Read the note when two writers may have touched the same lines.

## The Niv app and niv

The app and `niv` never sync the same folder at the same time. If the app has the folder open, niv waits ("The Niv app is syncing this folder, so niv waits.") and takes over by itself when the app quits or closes it. `niv sync --once` counts that as done, with exit 0, unless the app has stopped syncing the folder (exit 1). An older Niv app, which doesn't tell niv it has the folder, gets exit 6 (`synced-by-app`) instead of the wait.

## niv status

```
niv status [<note>] [--json] [--folder <path>]
```

How the folder's sync is doing, from this computer alone. It starts nothing.

```
$ niv status --folder ~/"Field notes"
Simple test · not running
~/Field notes · 76 notes · studio-mac
Not running. The last sync stopped at 03:02. Run niv or niv sync to start it.
Last change 03:02: sent Unsent 01.md.
```

A line like "1 on hold: niv holds." means something waits for you.

```
{"v":1,"time":"2026-10-29T06:02:13.095Z","type":"status","space":"Simple test","folder":"/Users/you/Field notes","device":"studio-mac","state":"not-running","notes":76,"holds":0,"failures":0,"pending":{"send":0,"receive":0,"notes":0},"lastEvent":{"time":"2026-10-29T06:02:09.714Z","type":"sent","path":"Unsent 01.md"},"running":false,"stoppedAt":"2026-10-29T06:02:09.724Z","lastState":"synced"}
```

- While a sync runs, `running` is true, `state` is its live state (see [Output for scripts](/p/docs/output-for-scripts)), `pid` and `since` name the process, and `percent` or `offlineSince` appear when they apply.
- Otherwise `state` is `not-running`, and `lastState` and `stoppedAt` say how and when the last sync ended.
- `holds` is a count, or `null` when niv can't tell.
- While the Niv app has the folder, it's a shorter object: `space`, `folder`, `device`, `state` and `owner` (`{app, since, syncing}`), no counts. `state` is `observing` when a niv sync waits for the app (with its `pid`), otherwise `not-running`.
- `lastEvent` is the last change a sync made here. For a move, `from` is the whole old path. The plain line says "renamed Plan.md from Draft.md" within one folder and "moved Ideas/Plan.md from Drafts/Plan.md" between folders.
- `unsynced` (`{links, files, examples}`), once a sync has looked, counts the symbolic links and the files that aren't notes, which don't sync, with up to ten paths each. The plain status says it in a line, such as "3 files here aren’t notes (images, PDFs and others) and don’t sync."
- `removed` (`[{count, at, restoreUntil}]`, one entry per day, kept while the notes can be restored) appears when a sync here removed notes from the Space because their files were gone. The plain status says it as "On 29 October, a sync removed 1 note from Simple test because its file is no longer in this folder. You can restore it from the Niv app, in Settings › History, until 28 November."
- `heldBack` (`{count, notes}`, each note a `path` and a `reason` such as `not-applied`) appears only when notes are stuck, such as a change the Space couldn't apply. The plain status names up to three, then "and N more", and the next step. There's nothing to choose in `niv holds`; if it stays after another `niv sync --once`, run that with `NIV_DEBUG=1` and send what it prints to niv.md/contact.
- `failing` (`{reason, since, cycles}`) appears when sync failed the same way three times in a row: the error word for word, when it began, and how many syncs failed. While a sync runs, the plain status says "Sync keeps failing with the same error: “…”." and what to do; after a sync that stopped that way, "Until it stopped, sync kept failing with the same error: “…”." and the next step.
- A folder that never synced gives only `folder`, `running: false` and `synced: false`.

### One note

`niv status <note>` says how one note stands. Name it as `niv publish` does: a path from the folder's top or from where you are, with or without `.md`, or its title when only one note has it. It reads only this computer, so it answers offline and while a sync runs.

```
$ niv status "Fresh 01" --folder ~/"Field notes"
Fresh 01.md is synced: the Space had this version at the last sync, 15:56.
```

```
{"v":1,"time":"2026-10-29T18:58:10.001Z","type":"note","path":"Fresh 01.md","state":"synced","syncedAt":"2026-10-29T18:56:29.944Z"}
```

| `state`        | What niv says                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `synced`       | "Fresh 01.md is synced: the Space had this version at the last sync, 15:56." (`syncedAt` in JSON)            |
| `pending`      | "Kelp.md has changes the Space doesn’t have yet. Run niv sync --once to send them."                          |
| `held`         | "Kelp.md is waiting for your choice. niv holds Kelp.md shows the choices."                                   |
| `local-only`   | "Kelp.md is local only: it never leaves this computer."                                                      |
| `not-in-space` | "Kelp.md isn’t in the Space yet. Run niv sync --once to add it."                                             |
| `unsynced`     | "Photo.png isn’t a note, so it doesn’t sync.", or "Link.md is a symbolic link, so it doesn’t sync."          |
| `missing`      | "Kelp.md was in the Space but isn’t in this folder now. niv sync decides what happened."                     |
| `never-synced` | "niv hasn’t synced this folder yet, so it can’t say how Kelp.md is. Run niv sync --once to start."           |
| `app`          | "The Niv app syncs this folder, and niv keeps no sync data of its own here, so it can’t say how Kelp.md is." |

While a sync runs, `pending` and `not-in-space` say that the running sync is sending or adding it. Every state exits with 0. A name that isn't a note here exits with 2 (`note-not-found`), and so does a title several notes share (`note-ambiguous`): name it by its path.

---

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