# Publish from the terminal

`niv publish` makes a note a public web page, or updates its page, exactly as **Publish** does in the app. See [Publish a note](/p/docs/publish-a-note) for what a page shows and who can publish.

## Name a note

Every command here takes notes the same way:

- a path from where you are (inside the folder `--folder` or `NIV_FOLDER` names, or the one you're in), with or without `.md`: `Start/Getting started`;
- a path from the folder's top;
- or a note's file name without `.md`, when only one note has it.

A name two notes share is refused, with both paths listed: use the path (exit 2). A folder is named the same way, with or without a trailing slash.

## niv publish

```
niv publish <note or folder>... [--except <note or folder>]... [--yes] [--dry-run] [--address <name>] [--json] [--folder <path>]
```

- A note that isn't public yet becomes a page. niv asks first; `--yes` skips the question, and without a terminal `--yes` is required (exit 2 without it).
- A note that's already public gets its page updated, unless the page already matches it.
- A folder publishes every note in it that can be published. Use `.` for the folder you're in. niv says which notes it skips and why: local only, not synced yet, empty, or left out with `--except`.
- `--except <note or folder>` leaves a note, or every note in a folder, out. Repeat it for more.
- `--dry-run` lists what would publish, update and be skipped. It changes nothing; run it first.
- `--address <name>`: the Space's first page needs a site address, `niv.md/p/<name>`. In a terminal niv asks for it; without one, give `--address`. It takes one note: publish that one first, then the rest.

```
$ niv publish . --dry-run --except "Start/The phone app.md" --folder ~/docs
All 35 pages already match their notes.
  Left out Start/The phone app.md (--except).
```

```
$ niv publish Start --dry-run --json --folder ~/docs
{"v":1,"time":"2026-10-29T05:53:48.509Z","type":"plan","dryRun":true,"publish":["Start/The phone app.md"],"update":[],"current":["Start/Find your way around.md","Start/Getting started.md","Start/Open your Obsidian vault.md","Start/Signing in.md"],"skipped":[],"address":{"path":"/p/docs"}}
```

`publish` would make new pages, `update` would update pages, `current` already match, and `skipped` gives each note's `reason`: `local-only`, `not-synced`, `empty` or `except`. When there's something to publish, `address` says where pages go: `path` for the Space's address (`null` when niv can't tell it yet), `needed: true` when the first page needs `--address`, or `given` with the address you gave. Only `--dry-run` prints the plan.

A real run, of one note or many, prints one `publish` object:

```
$ niv publish Welcome --yes --json --folder ~/docs
{"v":1,"time":"2026-10-29T05:54:18.787Z","type":"publish","pages":[{"path":"Welcome.md","url":"https://niv.md/p/docs/welcome","state":"published"}],"current":[],"skipped":[],"failed":[]}
```

- `pages` are the pages this run made or updated; `state` is `published` or `updated`.
- `current` lists the notes whose pages already matched, whether you named one note or many. On one note, the plain line says "The page for Welcome.md already matches the note."
- `skipped` gives `{path, reason}`, as in the plan, plus `trashed` for a note that went to the trash meanwhile.
- `failed` lists `{path, sentence}` for pages that couldn't publish (exit 1).

A page's address is fixed the first time the note is published. Renaming or moving the note, unpublishing it and publishing it again all keep it.

## niv unpublish

```
niv unpublish <note>... [--yes] [--json] [--folder <path>]
```

Takes the page offline. It asks first; `--yes` skips the question. It takes notes, not folders: name each one.

```
{"v":1,"time":"2026-10-29T05:54:38.735Z","type":"unpublish","pages":[{"path":"Old idea.md","state":"unpublished"}],"failed":[]}
```

A note without a page is already offline, so that's exit 0: "Old idea.md has no public page.", and in `--json` its `state` is `not-published`. A run of several takes the others offline as usual.

## niv published

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

The Space's public pages, one per line:

```
$ niv published --folder ~/docs
AI/Access levels.md       https://niv.md/p/docs/access-levels
AI/AI chat.md             https://niv.md/p/docs/ai-chat
```

```
{"v":1,"time":"2026-10-29T05:54:22.125Z","type":"published","pages":[{"path":"AI/Access levels.md","url":"https://niv.md/p/docs/access-levels","since":"2026-10-27T18:26:25.347Z","current":true}]}
```

`current` is false when the note changed after its page was last updated; the line says "page out of date". A Space with no pages: "Nothing published in Simple test yet."

## When it can't publish

- Only the Space's owners and editors can publish (exit 6).
- A local-only note, a note in the trash, or one with an image this device can't open: refused (exit 6).
- A note that hasn't synced yet waits for sync (exit 1). So does a run where nothing can be published, or where some pages failed.
- A name niv can't find, a name two notes share, an `--except` outside what you named or matching nothing, a bad `--address`, or `--address` on a Space that already has its address (`address-kept`): exit 2. An address someone already uses: exit 6.
- No terminal and no `--yes`, for publish or unpublish: exit 2.
- This computer's sign-in ended: exit 3.
- No server: "Niv can’t reach its server, so it can’t publish." (exit 5).

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

---

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