# Connect a folder

A folder syncs with one Space. `niv connect` makes the pair, `niv disconnect` undoes it, `niv spaces` lists what you can pick, and `niv stores` shows the sync data niv keeps on this computer.

## niv spaces

```
niv spaces [--json]
```

Your Spaces, numbered, with their ids.

```
$ niv spaces
  1  Notes        encrypted  3f1c2a90-5b7e-4d21-9c8a-0e6f4b2d7a15
  2  Simple test  encrypted  c9b667f8-4968-4d38-bf23-282a4fa9410e
```

With `--json`, one object with the list inside:

```
{"v":1,"time":"2026-10-29T05:51:39.737Z","type":"spaces","spaces":[{"id":"c9b667f8-4968-4d38-bf23-282a4fa9410e","name":"Simple test","encrypted":true,"nameHeld":false}]}
```

`nameHeld` is true for an encrypted Space whose name this device can't open yet; its row says "name not readable here".

## niv connect

```
niv connect [--space <name or id>] [--json] [--folder <path>]
```

Creates `.niv/` in the folder and pairs it with a Space.

- **An empty folder** receives the Space's notes.
- **A folder with files** is paired the way the Niv app pairs one: files that match link to their notes, and the rest become new notes. Many new files at once wait for a look first. See [Holds in the terminal](/p/docs/holds-in-the-terminal).

`--space` takes the Space's name or its id. Without it, niv asks in the terminal. With no terminal, `--space` is required (and the key file's passphrase, see [Sign in and keys](/p/docs/sign-in-and-keys)):

```
$ niv connect --folder ~/notes < /dev/null
There’s no terminal to ask which Space, so name it with --space <name or id>. niv spaces lists them.
```

A run from start to sync:

```
$ niv connect --space "Simple test" --folder ~/"Field notes"
Connected ~/Field notes to Simple test.
Run niv to watch, or niv sync to keep it running without the live view.
```

With `--json`:

```
{"v":1,"time":"2026-10-29T05:51:55.654Z","type":"connect","folder":"/Users/you/Field notes","space":"Simple test","state":"connected"}
```

`state` is `already` when the folder was connected to that Space before. When another folder on this computer syncs the same Space, `alsoSyncedBy` lists it.

Connecting a folder again to the same Space changes nothing and says "is already connected to Simple test." A folder connects to one Space: to connect it to another, run `niv disconnect` in it first (exit 6 until you do).

Other answers:

- An unknown Space name, or a name two Spaces share: exit 2. Use the id from `niv spaces`.
- Your home folder, a folder that holds it, or the disk's top: refused, exit 6. Connect a folder of notes.
- No Spaces on your account: exit 1. Create one in the Niv app.
- No server: exit 5.

See [Exit codes](/p/docs/exit-codes).

## niv disconnect

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

Stops syncing the folder. Its files stay, and so does its sync data, so connecting it again is quick. While a `niv sync` runs on the folder, it refuses ("Niv is syncing this folder (process 33325). Stop it, then run niv disconnect.", exit 1): stop that sync first. A folder that isn't connected: exit 4.

```
$ niv disconnect --folder ~/"Field notes"
Disconnected ~/Field notes from Simple test. Its files stay here.
Its sync data stays on this computer (3 MB), so connecting it again is quick. To remove it:
  niv stores --forget ~/'Field notes'
```

```
{"v":1,"time":"2026-10-29T05:59:27.019Z","type":"disconnect","folder":"/Users/you/Field notes","space":"Simple test","state":"disconnected","dataBytes":3458848}
```

## niv stores

```
niv stores [--forget <folder or store id>] [--yes] [--json]
```

The sync data niv keeps on this computer, one row per store, and what each one waits for. Usually that's one per folder.

```
$ niv stores
Niv’s sync data on this computer:
  ~/docs         Niv · Docs   9 MB  connected
  ~/Field notes  Simple test  3 MB  disconnected, on hold
  ~/old-notes    Niv · Docs   7 MB  folder gone

~/Field notes has 1 thing on hold. Connect the folder again, then decide it:
    13 new files at once
  niv connect --space c9b667f8-4968-4d38-bf23-282a4fa9410e --folder ~/'Field notes'
  niv holds --folder ~/'Field notes'

~/old-notes isn’t there any more. To remove its sync data (7 MB):
  niv stores --forget ~/old-notes
```

A row's state:

- **connected**: paired with its Space; no sync is running now.
- **syncing**: a niv sync is running on it now.
- **disconnected**: no longer paired; the sync data stays.
- **folder gone**: the folder isn't there any more.
- **synced by the Niv app**: the app keeps its own sync data for this folder; this row is niv's older copy.
- **folder not recorded**: niv can't tell which folder this sync data was for.

After the state: **has held files**, **on hold** (the folder as a whole waits), **has unsent edits**. Below the table, a paragraph names the notes and, where there's one, the command that deals with it, ready to paste. A store whose sync is running gets none: that sync is already sending.

`--json` gives one object, with a `stores` list:

```
{"v":1,"time":"2026-10-30T03:03:12.845Z","type":"stores","stores":[{"id":"17e4b186-6564-483d-a832-e71825012c33","folder":"/Users/you/docs","space":"Niv · Docs","spaceId":"f04ee3d1-2d9b-44a4-8fd5-b070a5ee87cc","bytes":11502472,"state":"connected","running":false,"unsent":0,"held":0,"folderHolds":0,"notes":[],"noteCount":46,"lastContact":"2026-10-29T19:14:05.350Z"}]}
```

`state` is `connected`, `syncing`, `disconnected`, `gone`, `app` or `null` (no folder recorded). `notes` lists only the notes waiting to send, by path; `noteCount` counts every note the store keeps. `lastContact` is when its last run last reached the server.

### Forget a store

`--forget` takes a folder or a store id and removes that folder's sync data. The notes stay in the folder and in the Space.

- It asks first. Without a terminal, it says what it would remove and stops (exit 2); add `--yes`.
- A connected folder is refused (exit 6): run `niv disconnect` in it first. So are unsent edits (exit 6): send them first.
- Sync data in use by a running niv or the app: exit 1. Stop it first.
- Nothing by that name, or a folder several stores name: exit 2. Use the store id from `niv stores --json`.
- In the folder's `.niv`, it removes the link to the Space and its lock, and keeps the settings (local-only marks included) and the trash; a `.niv` left empty goes too. The last line names what stayed: the settings, the trash (`.niv/trash`, the only local copy of the files sync removed), or both. Settings kept: keep `.niv` to connect again with them. A trash kept: copy back any files you want first. Either way you can delete it: the notes don't need it. Commands run in that folder then use the connected folder above it, if there is one.
- For a folder the Niv app syncs, niv removes only its own copy, and only if the app's copy already has every note as it is on disk.

```
$ niv stores --forget ~/old-notes --yes
Removed the sync data for ~/old-notes.
~/old-notes/.niv keeps this folder’s settings, local-only marks included. Keep it to connect again with them, or delete it: the notes don’t need it.
```

With a trash as well, the line says so: "~/old-notes/.niv keeps this folder’s settings, local-only marks included, and the files its sync removed, in ~/old-notes/.niv/trash. Keep it to connect again with those settings, or copy back any files you want and delete it: the notes don’t need it."

```
{"v":1,"time":"2026-10-29T05:59:27.513Z","type":"forget","id":"13a8a180-3eed-4dd9-bcb3-9c1c6135c886","folder":"/Users/you/old-notes","state":"removed"}
```

---

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