# Holds in the terminal

When niv can't tell what you meant, it doesn't guess. The file, or the folder as a whole, waits until you choose. Nothing is deleted while it waits. Some holds wait alone while the rest syncs; others stop more: a note whose file is gone stops sync until you answer, and a folder waiting for a look holds back every new file. The Niv app asks the same questions; see [When sync asks you something](/p/docs/when-sync-asks-you-something).

## See what waits

```
niv holds [--json] [--folder <path>]
```

```
$ niv holds --folder ~/"Field notes"
From the last niv sync, as of 03:02.
1 thing in Simple test waits for your choice. niv holds <path> shows one, with its choices.

Waiting for an answer before sync continues. Nothing is deleted until you answer.
If you know what happened, say so. If you don’t, keep both: nothing is deleted, and you can sort it out later.
  Evening page.md: no longer where it was when sync last ran.
```

A hold on the folder as a whole is listed as `this folder (.)`, with the command that lists its files when it has some.

`niv status` and `niv stores` also say when something is on hold. `niv sync --once` exits 1 on every hold except a name Windows can't use, a file kept apart, or a file Niv can't read yet: those leave it at 0 while they wait. A file another program has open counts after 2 minutes.

The list is as of the last niv sync, or the running one's latest look. Listing starts no sync and sends nothing, so it answers at once, offline, without the key file's passphrase. A hold that began since shows after the next `niv sync --once`:

```
$ niv holds --folder ~/"Field notes"
Nothing was on hold at the last niv sync, as of 23:43. Anything since shows after the next one.
```

A folder that never synced has nothing on hold yet: "niv hasn’t synced this folder yet, so nothing is on hold. Run niv sync --once to start."

`--show` and a choice are different: without a running sync, they open the folder's sync data themselves, can wait up to 30 seconds for it, and need the key file's passphrase (see [Sign in and keys](/p/docs/sign-in-and-keys)).

## Look at one

```
niv holds <path> [--show] [--json] [--folder <path>]
```

`niv holds <path>` says what happened and lists the choices, each as a flag:

```
$ niv holds "Evening page.md" --folder ~/"Field notes"
Evening page.md: no longer where it was when sync last ran.
Choose one:
  --keep-both        Not sure: keep both. The note stays in Simple test as it was. Nothing is deleted.
  --deleted          I deleted it. Removes the note from Simple test for everyone.
  --moved-to <path>  It’s now this file. Niv follows it as the same note.
```

`--show` changes nothing:

- for a file changed here and in the Space, it compares the file with the Space's version, line by line;
- for the folder as a whole (`.`), it lists the files that wait, the first ten and then "and N more";
- for any other hold, such as a file that's gone from the folder, there's nothing to compare: it says so, with exit 2 (`nothing-to-compare`).

## Choose

```
niv holds <path> --<choice> [--json] [--folder <path>]
```

```
$ niv holds "Evening page.md" --keep-both --folder ~/"Field notes"
```

The choice is a flag, as `niv holds <path>` lists it. Choose one thing at a time. A choice the hold doesn't offer is refused, with the ones it does (exit 2). When every hold has an answer, run `niv sync` (or `--once`) to carry on.

While a `niv sync` runs on the folder, a choice (or `--show`) is refused with exit 1 (`sync-running`): press h in its live view, or stop it and choose here. While the Niv app has the folder, choose in the app (`app-owns-folder`, exit 1).

## Every kind of hold

| What waits                                              | Why                                                                                                                                                                                | Choices                                                                                 |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| A file changed here and in the Space                    | Niv can't tell which version an edit started from, the Space has a different note by that name, it can't confirm an edit arrived, or the last edit couldn't be applied to the note | `--use-file`, `--use-shared`, `--keep-both`, `--save-copy`                              |
| A note whose file is gone                               | It isn't where it was when sync last ran                                                                                                                                           | `--keep-both`, `--deleted`, and `--moved-to <path>` when there's a new file it could be |
| Only new files, none missing                            | They become new notes when sync continues                                                                                                                                          | `--continue`                                                                            |
| Many new files at once (`.`)                            | More than usual, or a first sync of a folder with files                                                                                                                            | `--sync-now`                                                                            |
| Niv couldn't compare the new files with the Space (`.`) | Nothing was created                                                                                                                                                                | `--check-again`                                                                         |
| A file kept apart                                       | Niv couldn't compare it with the Space's note of the same name, so it downloaded the note separately                                                                               | `--send-separate`                                                                       |
| A file Niv couldn't read                                | Another program may have it open, or it isn't text                                                                                                                                 | None: it waits                                                                          |
| A file named like a note Niv can't read yet             | Waiting rather than risk a duplicate                                                                                                                                               | None: Niv checks again by itself                                                        |
| A new note marked local only after it was queued        |                                                                                                                                                                                    | `--keep-local`                                                                          |
| Changes the Space refused                               | Asking again gets the same answer                                                                                                                                                  | `--forget` (all of them)                                                                |
| A folder check that couldn't be taken                   |                                                                                                                                                                                    | `--check-again`                                                                         |
| A file another program has open                         |                                                                                                                                                                                    | None: Niv tries again by itself                                                         |
| A name Windows can't use                                |                                                                                                                                                                                    | None: rename it on a computer                                                           |

What each choice does:

- `--use-file`: the note becomes what the file says.
- `--use-shared`: the file becomes what the Space's note says.
- `--keep-both`: for a changed file, your version is saved as a private copy next to it, named like `Ideas (my version).md` and marked local only, and the file becomes what the note says; for a missing file, the note stays in the Space as it was. Nothing is deleted.
- `--save-copy`: saves a private copy of the file first. It stays on hold until you choose.
- `--deleted`: you deleted it; the note leaves the Space for everyone. When it's the last answer, niv sends the trash then and there, so the next sync has nothing left to say about it.
- `--moved-to <path>`: it's now this file; Niv follows it as the same note. A move that left the file unchanged is followed by itself, so this choice is only for one that was also edited. The next sync sends the move with the edit.
- `--continue`: the new files become notes.
- `--sync-now`: files that match a note link to it; the rest become notes.
- `--check-again`: Niv looks at the folder again before you answer.
- `--send-separate`: it joins the Space as a separate note, next to the one with its name.
- `--keep-local`: it stays on this device and never joins the Space.
- `--forget`: drops all the refused changes at once; no file changes.

## When a note was deleted elsewhere

If you edit a file here while another device deletes its note, your edit isn't lost and nothing waits: niv keeps it as a new note next to where it was, named with "(copy)" ("(copy 2)" and so on if that's taken). `niv sync` shows it as a move marked "(deleted on another device)"; with `--json` its `message` says "Ideas.md was deleted on another device; your edit is kept as Ideas (copy).md." Delete the copy if you don't need it.

## For scripts

`niv holds --json` is one object, with a `holds` list:

```
{"v":1,"time":"2026-10-30T02:50:43.062Z","type":"holds","holds":[{"kind":"divergence","path":"R22 gone.md","since":"2026-10-30T02:50:31.109Z","reason":"missing","resolutions":["keep-both","deleted"]}],"asOf":"2026-10-30T02:50:40.860Z"}
```

```
{"v":1,"time":"2026-10-28T22:51:05.471Z","type":"holds","holds":[{"kind":"publication","path":".","reason":"many-new-files","resolutions":["sync-now"],"facts":{"count":3},"files":["Fresh 01.md","Fresh 02.md","Fresh 03.md"]}]}
```

- `kind`: `file`, `divergence`, `publication`, `held-create`, `refused`, `name` or `in-use`.
- `resolutions`: the choices, without their `--`. `moved` is the flag `--moved-to <path>`. An empty list means there's nothing to choose.
- `since`: when the hold began; left out when niv didn't see it begin.
- `asOf`: the time of the sync the list comes from. A folder that never synced gives `holds: []` and `synced: false` instead.
- While the Niv app syncs the folder, `holds` is `null` and `state` is `observing`: ask in the app.

`niv holds <path> --show --json` is a `show` object with `path`, `file`, `space` and `same`; for `.`, `path` and `files`.

A choice with `--json`:

```
{"v":1,"time":"2026-10-30T20:22:38.204Z","type":"resolved","path":"R24 t1.md","choice":"deleted","continues":true}
{"v":1,"time":"2026-10-30T20:22:38.491Z","type":"trashed","path":"R24 t1.md"}
```

`continues` is true when that was the last hold and sync can go on. Then a `trashed` line follows for each note that answer sent to the trash, once the Space has it, as `niv sync` writes them; an earlier `--deleted` answer's note is included if the Space has it by then; otherwise the next `niv sync` says it. An answer that leaves other holds waiting is `resolved` alone. `choice` is the flag without `--` (`moved` for `--moved-to`), and `copy` names the private copy when one was saved (`"copy":"Ideas (my version).md"`).

Errors: nothing on hold at that path is `not-held`, and a choice the hold doesn't offer, a `--moved-to` path it can't be, or two choices at once are `usage` (exit 2); a choice that couldn't be carried out is `failed`, a `--show` that couldn't get the Space's version `unavailable`, a hold that still waits after the choice `held` (with `reason: "sent-unconfirmed"` when Niv sent the choice but the Space didn't confirm it within 30 seconds, for `--deleted` its trash: don't choose again, the next `niv sync` confirms it or shows the hold again), and `sync-running` or `app-owns-folder` as above (exit 1).

---

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