# The niv command

`niv` keeps a folder of notes in sync with a Space from a terminal, end-to-end encrypted, the same way the Niv app does. Use it on a computer with no screen, like a server, from a script or an agent, or wherever you'd rather not open the app.

## Start in four lines

```
niv sign-in
cd ~/notes
niv connect
niv
```

1. `niv sign-in` lets this computer in as a device of your account. See [Sign in and keys](/p/docs/sign-in-and-keys).
2. `cd` into the folder you want to sync.
3. `niv connect` asks which Space it syncs with. See [Connect a folder](/p/docs/connect-a-folder).
4. `niv` alone opens the live view. Press q to stop it. See [Keep a folder in sync](/p/docs/keep-a-folder-in-sync).

To install it, see [Install and update niv](/p/docs/install-and-update-niv).

## The commands

| Group           | Command          | What it does                                                                         |
| --------------- | ---------------- | ------------------------------------------------------------------------------------ |
| Start           | `niv sign-in`    | Lets this computer in as a device of your account                                    |
|                 | `niv connect`    | Syncs this folder with a Space                                                       |
|                 | `niv`            | With no command: the live view                                                       |
| Keep it running | `niv sync`       | Keeps this folder in sync, without the live view                                     |
|                 | `niv status`     | How this folder's sync is doing, or one note's                                       |
|                 | `niv holds`      | Files waiting for your choice                                                        |
| Publish         | `niv publish`    | Publishes a note as a web page, or updates its page                                  |
|                 | `niv unpublish`  | Takes a note's page offline                                                          |
|                 | `niv published`  | This Space's public pages                                                            |
| This device     | `niv device`     | Name and fingerprint                                                                 |
|                 | `niv spaces`     | Your Spaces                                                                          |
|                 | `niv disconnect` | Stops syncing this folder                                                            |
|                 | `niv stores`     | The sync data niv keeps on this computer                                             |
|                 | `niv sign-out`   | Removes this device's keys                                                           |
|                 | `niv upgrade`    | Updates niv to the newest version                                                    |
| For agents      | `niv skill`      | How an AI agent should use niv                                                       |
|                 | `niv databases`  | Reads and changes a Space's databases. See [niv databases](/p/docs/niv-databases)    |
|                 | `niv mcp`        | Lets an app that speaks MCP read notes and databases. See [niv mcp](/p/docs/niv-mcp) |

`niv help <command>` explains each one in the terminal, for the version you have, offline.

## How it thinks

- **A folder, a Space.** A connected folder has a `.niv` folder at its top and syncs with exactly one Space. Your notes are plain Markdown files in it.
- **Which folder.** Every command works on the folder you're in, or the one above it that's connected. `--folder <path>` names another, and `NIV_FOLDER=<path>` does the same for a whole session. `--folder` wins over `NIV_FOLDER`.
- **Holds.** When niv can't tell what you meant, it doesn't guess: the file waits in [Holds in the terminal](/p/docs/holds-in-the-terminal) until you choose. Nothing is deleted while it waits.
- **Sync data.** niv keeps each folder's sync data on this computer, apart from the app's. See `niv stores` in [Connect a folder](/p/docs/connect-a-folder).
- **For scripts.** Add `--json` for JSON on stdout, and read the exit status. See [Output for scripts](/p/docs/output-for-scripts) and [Exit codes](/p/docs/exit-codes).

## Options every command takes

- `--folder <path>`: the folder to work on.
- `--json`: JSON on stdout and nothing else, one object per command; `niv sync --json` and `niv --json` print one event per line instead, and never open the live view. `--help`, `--version`, `niv help` and `niv skill` stay plain text, and `niv sign-in` prints JSON only for an error. See [Output for scripts](/p/docs/output-for-scripts).
- `--no-color`: no colour. `NO_COLOR` set to anything does the same.
- `--help` (or `-h`) after a command: its help. `niv --version`: the version.

`niv help keys` explains starting without a terminal, `niv help json` the JSON, and `niv help environment` the variables you can set.

## More

- [Using niv from an agent](/p/docs/using-niv-from-an-agent): the rules an agent should follow.
- [Troubleshooting niv](/p/docs/troubleshooting-niv): what a message means and what to do.

## What it leaves to the app

Creating a Space, setting up encryption the first time, and using your recovery file all happen in the Niv app.

The app and `niv` never sync the same folder at the same time. If `niv` is syncing a folder the app has open, the app's sync line says **Syncing through the niv command** and waits. See [Sync status](/p/docs/sync-status).

---

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