---
title: "Niv CLI"
description: "niv is Niv’s command line for Mac, Linux and Windows: install it with Homebrew or one line, then sync a folder of Markdown notes with a Space, publish notes and work with databases from a terminal, a script or an AI agent."
canonical: https://niv.md/cli
language: en
last_updated: 2026-11-14T17:16:54.000Z
---

# Niv CLI

niv is Niv’s command line. It keeps a folder of Markdown notes in sync with a Space the same way the Niv app does, encrypted end to end in every Space created now. Use it on a server, in a script, from an AI agent, or wherever you’d rather not open the app. It’s free, like sync.

## Install

On a Mac, with Homebrew. On Linux and Windows, one line. niv --version says which version you have; niv upgrade updates it.

- macOS (Homebrew): `brew install niv-md/tap/niv`
- Linux: `curl -fsSL https://releases.niv.md/install.sh | sh`
- Windows (PowerShell): `irm https://releases.niv.md/install.ps1 | iex`

The Homebrew formula is public, in Niv’s tap on GitHub: [niv-md/homebrew-tap](https://github.com/niv-md/homebrew-tap).

## Start in four lines

1. `niv sign-in`: Lets this computer in as a device of your account. You approve it and type your encryption passphrase yourself.
2. `cd ~/notes`: Go to the folder you want to sync.
3. `niv connect`: Asks which Space the folder syncs with.
4. `niv`: Alone, opens the live view. Press q to stop it. niv sync does the same with no screen.

## The commands

### Start

- `niv sign-in`: Let this computer in as a device of your account
- `niv connect`: Sync this folder with a Space

### Keep it running

- `niv sync`: Keep this folder in sync, without the live view
- `niv status`: How this folder’s sync is doing
- `niv holds`: Files waiting for your choice

### Publish

- `niv publish`: Publish a note as a web page, or update its page
- `niv unpublish`: Take 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`: Stop syncing this folder
- `niv stores`: The sync data niv keeps on this computer
- `niv sign-out`: Remove this device’s keys
- `niv upgrade`: Update niv to the newest version

### For agents

- `niv skill`: How an AI agent should use niv
- `niv databases`: List, read and change a Space’s databases
- `niv mcp`: Let an AI app read this folder’s notes, and read and change a Space’s databases

## For scripts and agents

Every command takes --folder <path> (or NIV_FOLDER) and --json, which prints JSON on stdout. niv help <command> lists a command’s options. niv skill prints a skill written for the version you have, for an AI agent to read.

niv mcp is a local MCP server for apps like Claude Code, Cursor and Claude Desktop: [Niv MCP server](https://niv.md/mcp).

The whole guide is in the docs: [Niv Docs](https://niv.md/docs). [What changed in each niv version](https://niv.md/changelog/cli).

---

More: [Niv](https://niv.md/) · [About](https://niv.md/about) · [Contact](https://niv.md/contact) · [Privacy](https://niv.md/privacy) · [Encryption](https://niv.md/encryption) · [Terms](https://niv.md/terms) · [llms.txt](https://niv.md/llms.txt) · [Português (Brasil)](https://niv.md/pt-br/cli)
