# Output for scripts

Every command takes `--json`. With it, stdout carries JSON and nothing else; questions, warnings and the usage line go to stderr. (`niv sign-out`'s warning is the exception: it's inside its JSON object.) Declining a question in a terminal prints nothing and exits 0. Read the exit status too: it says the same as the JSON. See [Exit codes](/p/docs/exit-codes).

## The shape

Every command prints one object on one line, with `"v": 1`, `time` and `type`, and any lists inside it:

```
{"v":1,"time":"2026-10-29T05:53:56.024Z","type":"published","pages":[]}
```

`niv sync --json` and bare `niv --json` are the exception: they print one event per line, as things happen, each with `v`, `time` and `type`. `--help`, `--version`, `niv help` and `niv skill` stay plain text, and `niv sign-in` asks in the terminal and prints JSON only for an error.

An error, from any command, is one object, and the exit status is never 0:

```
{"v":1,"time":"2026-10-29T05:51:39.997Z","type":"error","code":"not-connected","message":"~/notes isn’t connected to a Space. Run niv connect, or run niv from a connected folder."}
```

`code` is stable: branch on it. `message` is the sentence a person would read, and its words can change.

## The objects, by type

| `type`       | From                      | Fields                                                                                                                                                                                                                                                                                                                                                            |
| ------------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `spaces`     | `niv spaces`              | `spaces: [{id, name, encrypted, nameHeld}]`                                                                                                                                                                                                                                                                                                                       |
| `connect`    | `niv connect`             | `folder`, `space`, `state` (`connected` or `already`), `alsoSyncedBy`                                                                                                                                                                                                                                                                                             |
| `disconnect` | `niv disconnect`          | `folder`, `space`, `state`, `dataBytes`                                                                                                                                                                                                                                                                                                                           |
| `status`     | `niv status`              | `space`, `folder`, `device`, `state`, `notes`, `holds`, `failures`, `pending`, `lastEvent`, `running`, and `unsynced`, `heldBack`, `removed`, `failing` when they apply; never synced: `folder`, `running`, `synced`; while the Niv app has the folder: `space`, `folder`, `device`, `state`, `owner`. See [Keep a folder in sync](/p/docs/keep-a-folder-in-sync) |
| `note`       | `niv status <note>`       | `path`, `state`, and `syncedAt` when it's synced                                                                                                                                                                                                                                                                                                                  |
| `holds`      | `niv holds`               | `holds: [{kind, path, reason, resolutions, since}]` and `asOf` (the sync the list is from); `synced: false` before a first sync; `holds` is `null` while the Niv app syncs                                                                                                                                                                                        |
| `resolved`   | a hold's choice           | `path`, `choice`, `continues`                                                                                                                                                                                                                                                                                                                                     |
| `show`       | `niv holds <path> --show` | `path`, `file`, `space`, `same`; for `.`, `path` and `files`                                                                                                                                                                                                                                                                                                      |
| `plan`       | `niv publish --dry-run`   | `publish`, `update`, `current`, `skipped`, `address`                                                                                                                                                                                                                                                                                                              |
| `publish`    | `niv publish`             | `pages: [{path, url, state}]`, `current`, `skipped`, `failed`                                                                                                                                                                                                                                                                                                     |
| `unpublish`  | `niv unpublish`           | `pages: [{path, state}]` (`unpublished`, or `not-published` for a note that has no page), `failed`                                                                                                                                                                                                                                                                |
| `published`  | `niv published`           | `pages: [{path, url, since, current}]`                                                                                                                                                                                                                                                                                                                            |
| `stores`     | `niv stores`              | `stores: [{id, folder, space, spaceId, bytes, state, running, unsent, held, folderHolds, notes, noteCount, lastContact}]`: `notes` are those waiting to send, `noteCount` every note the store keeps (`null` when niv can't tell), `lastContact` its last run's last reach of the server (`null` if it never reached it)                                          |
| `forget`     | `niv stores --forget`     | `id`, `folder`, `state`                                                                                                                                                                                                                                                                                                                                           |
| `device`     | `niv device`              | `name`, `fingerprint`, `signedInAs`                                                                                                                                                                                                                                                                                                                               |
| `sign-out`   | `niv sign-out`            | `state`, `endedOnServer`, and `warning` when there's one                                                                                                                                                                                                                                                                                                          |
| `upgrade`    | `niv upgrade`             | `state`, `message`, and `from`, `to`, `install` or `url` when they apply. See [Install and update niv](/p/docs/install-and-update-niv)                                                                                                                                                                                                                            |

Each command's page shows its own JSON: [Connect a folder](/p/docs/connect-a-folder), [Keep a folder in sync](/p/docs/keep-a-folder-in-sync), [Holds in the terminal](/p/docs/holds-in-the-terminal), [Publish from the terminal](/p/docs/publish-from-the-terminal), [Sign in and keys](/p/docs/sign-in-and-keys), [Install and update niv](/p/docs/install-and-update-niv).

## Paths in JSON

A `folder` is always an absolute path (in `stores` and `forget` it can be `null`, when niv didn't record one). Note paths (`path`, `from`, `files`, the lists in `plan` and `publish`) are always from the folder's top, with `/`.

## niv sync --json events

```
{"v":1,"time":"2026-10-29T05:52:50.502Z","type":"state","state":"syncing"}
{"v":1,"time":"2026-10-29T05:52:50.976Z","type":"sent","path":"Ideas/Morning.md","new":true}
{"v":1,"time":"2026-10-29T05:53:19.883Z","type":"sent","path":"Unsent 01.md"}
{"v":1,"time":"2026-10-29T05:53:26.268Z","type":"moved","path":"Ideas/Second.md","from":"Second.md"}
{"v":1,"time":"2026-10-29T05:53:28.067Z","type":"state","state":"synced"}
```

| `type`     | Fields                                                                                                                                                                                                          | Means                                                                                                                                                                                                        |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `state`    | `state`, and `percent`, `reading`, `owner`, `waiting`, `pid`, `holds`, `failing`, `message` when they apply                                                                                                     | Sync changed state                                                                                                                                                                                           |
| `sent`     | `path`, `new`                                                                                                                                                                                                   | An edit, or a new note, went to the Space                                                                                                                                                                    |
| `received` | `path`, `new`                                                                                                                                                                                                   | An edit, or a new note, arrived                                                                                                                                                                              |
| `moved`    | `path`, `from`, and `reason`, `message` for a kept copy                                                                                                                                                         | A note moved or was renamed; a path ending in `/` is a folder                                                                                                                                                |
| `trashed`  | `path`                                                                                                                                                                                                          | A note went to the trash; a path ending in `/` is a folder, removed for everyone                                                                                                                             |
| `removed`  | `count`, `space`, `spaceId`, `message`                                                                                                                                                                          | A sync removed notes from the Space because their files are gone; `message` says where to restore them                                                                                                       |
| `held`     | `path`, `reason`                                                                                                                                                                                                | A file is on hold                                                                                                                                                                                            |
| `progress` | `done`, `total`                                                                                                                                                                                                 | How far the first receive is, once per whole percent and at the end; also while `--once` waits for an encrypted Space's notes to be read (most of all the first run after an update), once per whole percent |
| `error`    | `code`, `message`, `path` when it's about a file; for `receiving` and `catching-up` also `space`, `spaceId`, `done` and `total`, for `sending` `space`, `spaceId` and `notes` (how many hold unconfirmed edits) | Something failed; for `--once`, the last line before it exits with an error                                                                                                                                  |

A field is there only when it's true or known. `new` appears only as `true`, once per new note.

An `error` event about one file doesn't decide the exit: a run can print one and still end with 0. `--once` prints no closing line when it ends with 0.

A `moved` with `reason: "deleted-elsewhere"` is an edit kept as a copy because another device deleted its note; `message` says where it went. See [Holds in the terminal](/p/docs/holds-in-the-terminal).

`niv sync` prints nothing more when it's stopped: ctrl+c exits 130, a `SIGTERM` 0. With `--quiet`, only `error` events print.

### The state keys

| `state`                                                                                  | Means                                                                                                                                                                                                                                            |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `connecting`                                                                             | Reaching the Space                                                                                                                                                                                                                               |
| `reading`                                                                                | Reading this folder, or the Space's notes, as sync starts                                                                                                                                                                                        |
| `receiving`                                                                              | Receiving notes; `percent` says how far                                                                                                                                                                                                          |
| `syncing`                                                                                | Sending and receiving                                                                                                                                                                                                                            |
| `synced`, `restored`                                                                     | The folder and the Space match                                                                                                                                                                                                                   |
| `offline`                                                                                | Can't reach Niv; it keeps trying                                                                                                                                                                                                                 |
| `observing`                                                                              | The Niv app syncs the folder; niv waits. `owner` says who and since when                                                                                                                                                                         |
| `divergence-held`, `action-needed`, `files-to-review`, `held-creates`, `encryption-held` | Something waits for you; see [Holds in the terminal](/p/docs/holds-in-the-terminal). `divergence-held` says how many in `holds`                                                                                                                  |
| `refused`                                                                                | The Space refused changes                                                                                                                                                                                                                        |
| `in-use`                                                                                 | Another program has files open                                                                                                                                                                                                                   |
| `receive-only`                                                                           | Sending is paused; edits wait here                                                                                                                                                                                                               |
| `conflict`, `error`                                                                      | Something went wrong. If one lasts 2 minutes, `--once` ends with an `error` event that says why. `error` carries `failing` and a `message` when sync failed the same way three times in a row (see below); otherwise neither carries a `message` |
| `encrypting`                                                                             | The Space is being encrypted                                                                                                                                                                                                                     |
| `setting-up`                                                                             | The Space is being set up                                                                                                                                                                                                                        |
| `signed-out`                                                                             | This computer's sign-in ended                                                                                                                                                                                                                    |
| `stopped`, `start-failed`                                                                | Sync stopped; `message` says why                                                                                                                                                                                                                 |

### When sync keeps failing

When sync fails three times in a row for the same reason, the state turns `error` with `failing: {reason, since}`: `reason` is the error, word for word, and `since` when the first of those failures happened. One good sync clears it; `offline` stays `offline`. The `message` says it:

```
{"v":1,"time":"2026-10-30T20:49:01.000Z","type":"state","state":"error","failing":{"reason":"canonicalize folder failed: No such file or directory (os error 2)","since":"2026-10-30T20:48:01.000Z"},"message":"Sync keeps failing with the same error: “canonicalize folder failed: No such file or directory (os error 2)”. niv keeps trying, and your edits stay in this folder. If it doesn’t clear, stop sync, then run niv sync --once with NIV_DEBUG=1 and send what it prints to niv.md/contact."}
```

The plain line adds the first sentence after the key, once: `state error Sync keeps failing with the same error: “…”.` A reason longer than 200 characters is cut short in the sentences; `failing` keeps it whole. `niv status --json` has `failing` too, with `cycles`, how many syncs failed, while a sync runs and after it stopped that way.

If `--once` ends on it, its `error` event (exit 1) has the same first sentence, then why it stopped and what to do. After 2 minutes, with code `error`:

```
Sync keeps failing with the same error: “canonicalize folder failed: No such file or directory (os error 2)”. niv sync --once stopped after waiting 2 minutes. Your edits stay in this folder. Run niv sync --once again with NIV_DEBUG=1 and send what it prints to niv.md/contact.
```

At its `--timeout`, with code `timeout`, it starts with "niv sync --once stopped at its limit of 5m, before the folder and the Space matched.", then the same sentences without the 2 minutes.

## What to rely on

- `"v": 1` is the format's version.
- Keys are stable; sentences aren't.
- New fields and new `type` or `state` values can appear: ignore what you don't know.
- `niv help json` lists the same, for the version you have.

---

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