# Sign in and keys

`niv` signs in as a device of your account, like a new phone or laptop. Each device has its own keys, so you can remove one without touching the others.

## niv sign-in

```
niv sign-in
```

It takes no options, and it needs a terminal: it asks for your passphrases.

1. **Approve this computer.** niv opens niv.md/device in your browser and shows a code. Approve there only if the page shows the same code. With no browser on this computer, niv prints the address and a code: open it on any device where you're signed in to Niv, and enter the code.
2. **Unlock your notes** with your encryption passphrase. See [Encryption](/p/docs/encryption).
3. **Name this device.** niv offers this computer's name; press return to keep it. The name shows in **Settings › Encryption › Devices**.
4. **Choose a passphrase for the key file.** It locks this device's keys on this computer. Use at least 12 characters.
5. On a Mac, or a Linux desktop with a keyring, niv offers to remember the key file's passphrase in the macOS Keychain or your login keyring, so it opens without asking. It doesn't offer over SSH, and on a Mac only a niv signed by Niv can use the Keychain.

Abridged; the names, codes and keys are examples.

```
$ niv sign-in
Opened niv.md/device in your browser. Approve there if it shows WXYZ-1234.
Approved. Signed in as you@example.com.
Unlock your notes with your encryption passphrase.
Encryption passphrase:
Name this device [studio-mac]:
This device keeps its keys in a key file, locked with a passphrase of its own.
Choose the key file’s passphrase:
Again:
studio-mac is in. Your key K4QX 7M2D 9FHT W3NB PL6R 2VCA XE8J 5TQM.
Next: niv connect
```

Bare `niv` on a computer that isn't signed in starts the same steps.

When it can't go on:

- No terminal: "niv sign-in asks for your passphrases, and there’s no terminal to ask in. Run it once in a terminal; after that, niv runs without one (see niv help keys)." Exit 2.
- Already signed in: "This computer is already signed in to Niv as … To sign in again, run niv sign-out first." Exit 3.
- The code expired or was denied: run `niv sign-in` again for a new one. Exit 3.
- The encryption passphrase was wrong three times: exit 3. Run it again.
- No connection: "Niv can’t reach its server, so sign-in can’t start." Exit 5.
- Encryption isn't set up for your account yet: set it up in the Niv app first.
- Forgot your encryption passphrase: set a new one in the Niv app with your recovery file, then sign in again. niv never uses the recovery file.

## Start without a terminal

Once signed in, the other commands only need the key file's passphrase. Where nobody can type it, give it one of these:

|                                  |                                                                                                            |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `NIV_KEY_PASSPHRASE=…`           | the passphrase itself, for every command                                                                   |
| `NIV_KEY_PASSPHRASE_FILE=<path>` | a file that holds only the passphrase, for every command                                                   |
| `--passphrase-file <path>`       | the same file, as a flag (systemd credentials, Docker secrets). Only `niv sync` and `niv sign-out` take it |

Without any of them and no terminal, a command that needs the keys stops: "Sync needs this device’s key passphrase, and there’s no terminal to ask in. See niv help keys." Exit 3.

The key file is at `~/.config/niv/key.json` (under `XDG_CONFIG_HOME` when it's set; `%APPDATA%\niv\key.json` on Windows). To use another:

|                          |                                                                |
| ------------------------ | -------------------------------------------------------------- |
| `NIV_KEY_FILE=<path>`    | where the key file is                                          |
| `NIV_KEY_FILE_CONTENT=…` | the whole key file, for CI. It stays locked by its passphrase. |

Never put the passphrase on the command line: other users on this computer can see it. niv won't open a key file that other users can read or change; it says which `chmod` to run.

`niv help keys` says the same in the terminal.

## niv device

```
niv device [--json]
```

This device's name, the account it's signed in as, and its key's fingerprint. Compare the fingerprint with the one in **Settings › Encryption › Devices**.

```
$ niv device
studio-mac · you@example.com
Your key K4QX 7M2D 9FHT W3NB PL6R 2VCA XE8J 5TQM
```

```
{"v":1,"time":"2026-10-29T05:51:39.881Z","type":"device","name":"studio-mac","fingerprint":"K4QX 7M2D 9FHT W3NB PL6R 2VCA XE8J 5TQM","signedInAs":"you@example.com"}
```

## niv sign-out

```
niv sign-out [--passphrase-file <path>]
```

Signs out and deletes this device's key file, and forgets a passphrase it remembered. Your files stay as they are. The device stays in your account until you remove it in **Settings › Encryption › Devices** on another device.

niv uses the key file's passphrase, from a terminal, `--passphrase-file`, the variables above or the Keychain or keyring where niv remembered it, to end the sign-in on the server too. Without one it still signs out and deletes the key file (exit 0), and says "Niv couldn’t end this sign-in on the server; it ends by itself within 7 days."

With `--json`, one object:

```
{"v":1,"time":"2026-10-29T06:40:12.031Z","type":"sign-out","state":"signed-out","endedOnServer":true}
```

`endedOnServer` is false when the sign-in couldn't be ended on the server. If niv couldn't forget a passphrase it had remembered, the object carries `warning`, with `code` `passphrase-left` and the sentence in `message`; it's still exit 0.

`niv device` and `niv sign-out` on a computer that isn't signed in: "This computer isn’t signed in to Niv. Run niv sign-in." Exit 3.

## If this device's keys leak

Remove the device in **Settings › Encryption › Devices** on another device. Its keys stop working at once.

---

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