# noz-cli

A terminal REPL and PowerShell module for [noz](https://git.kryptomrx.de/krypto/noz) — a self-hosted digital garden built with Next.js.

Navigate, create, and manage your notes from the command line. Ships as a Native AOT binary (~7.6 MB, no .NET runtime required) and a PowerShell module for scripting and automation.

---

## Install

### macOS / Linux — binary

Download from [Releases](../../releases) and place on your PATH:

```bash
# macOS Apple Silicon
curl -L https://git.kryptomrx.de/krypto/noz-cli/releases/latest/download/noz-osx-arm64 \
  -o /usr/local/bin/noz && chmod +x /usr/local/bin/noz
```

### PowerShell module

Requires PowerShell 7.2+ and .NET 8.

```powershell
git clone https://git.kryptomrx.de/krypto/noz-cli
cd noz-cli
./Noz.PowerShell/Install-NozModule.ps1
```

---

## Setup

```bash
noz init https://your-noz-instance.com your-api-token
```

Writes `~/.config/noz/config.json`. The token is the CLI token configured in your `noosphere.toml` under `[cli]`.

---

## REPL

```bash
noz
```

Starts the interactive REPL. A local note cache (`~/.cache/noz/notes.json`) is used for instant startup; a background refresh runs silently.

### Navigation

| Command | Description |
|---------|-------------|
| `ls` | List topics (at root) or notes in the current folder |
| `ls -la` | Detailed list with status, date, language |
| `cd <topic>` | Enter a topic or sub-folder |
| `cd ..` | Go up one level |
| `tree` | Full hierarchy as a tree |

### Notes

| Command | Description |
|---------|-------------|
| `cat <slug>` | Print a note (rendered markdown) |
| `cat --raw <slug>` | Print raw markdown |
| `new <name>` | Create a note and open in editor |
| `new -c <name>` | Create a note and open in VS Code |
| `new --template <name> <slug>` | Create from a template |
| `edit <slug>` | Edit a note in terminal editor |
| `edit -c <slug>` | Edit in VS Code |
| `mv <old> <new>` | Rename a note — rewrites all inbound wikilinks |
| `rm <slug>` | Delete a note |
| `search <query>` | Full-text search (Meilisearch) |
| `search <query> --topic <topic>` | Search within a topic |

### Folders

| Command | Description |
|---------|-------------|
| `mkdir <name>` | Create a folder (writes `_index.md`, navigates in) |

### Linking

| Command | Description |
|---------|-------------|
| `link <source> <target>` | Add a wikilink from source to target |
| `link <source> <target> --both` | Bidirectional link |

### Templates

| Command | Description |
|---------|-------------|
| `templates` | List available templates |
| `new --template <name> <slug>` | Create a note from a template |

Templates live in `content/noosphere/_templates/<name>.md` on the server. Placeholders: `{{title}}`, `{{topic}}`, `{{date}}`, `{{status}}`, `{{lang}}`.

### Sync

| Command | Description |
|---------|-------------|
| `sync <local-path>` | Pull changed notes from server to local folder |
| `sync <local-path> --all` | Pull everything (ignore local hashes) |
| `sync <local-path> --dry-run` | Preview what would be downloaded |
| `push <local-path>` | Push local `.md` files to server |
| `status <local-path>` | Show diff between local folder and server |

### Other

| Command | Description |
|---------|-------------|
| `version` | Show version and git hash |
| `config` | Show editor settings |
| `config editor <name>` | Set terminal editor |
| `config code-editor <name>` | Set GUI editor |
| `clear` | Clear the screen |
| `help` | List all commands |
| `exit` | Quit |

**Ctrl+C** while idle exits the REPL. During a command it cancels only that command.

---

## PowerShell Module

After installing, import with:

```powershell
Import-Module Noz
```

### Note commands

```powershell
# List and filter notes
Get-NozNote
Get-NozNote -Topic psychologie
Get-NozNote -Status evergreen
Get-NozNote -Lang de

# Read content
Get-NozNoteContent -Slug psychologie/flow-theorie

# Create / update / delete
New-NozNote -Slug kochen/pasta -Title "Pasta Carbonara" -Topic kochen
Set-NozNote -Slug psychologie/flow-theorie -Markdown $content
Remove-NozNote -Slug alte-notiz

# Rename (rewrites all inbound links)
Rename-NozNote -Slug psychologie/old -NewSlug psychologie/new

# Change status
Set-NozNoteStatus -Slug psychologie/flow-theorie -Status evergreen
```

### Search

```powershell
Find-NozNote "flow"
Find-NozNote "hydroponik" -Topic biosysteme -Limit 5
```

### Graph & analysis

```powershell
# All wikilink edges
Get-NozGraph
Get-NozGraph -Source psychologie/flow

# Notes with no incoming links
Get-NozOrphans
Get-NozOrphans -Topic psychologie

# Garden-wide statistics
Measure-NozGarden

# Link two notes
Add-NozLink -Source psychologie/flow -Target biosysteme/brs-konzept
Add-NozLink -Source a -Target b -Both
```

### Templates

```powershell
Get-NozTemplate
Get-NozTemplate rezept
```

### Pipeline examples

```powershell
# Promote all seed notes in a topic to budding
Get-NozNote -Topic psychologie -Status seed |
  Set-NozNoteStatus -Status budding -WhatIf

# Export all evergreen notes as markdown files
Get-NozNote -Status evergreen |
  ForEach-Object { Get-NozNoteContent $_.Slug } |
  ForEach-Object { Set-Content "$($_.Slug).md" $_.Markdown }

# Find orphans and link them to a topic overview
Get-NozOrphans -Topic biosysteme |
  Add-NozLink -Target biosysteme/uebersicht
```

---

## Configuration

`~/.config/noz/config.json`:

```json
{
  "server_url": "https://your-noz-instance.com",
  "token": "...",
  "editor": "nano",
  "code_editor": "code"
}
```

Editor is auto-detected from `$EDITOR` if not set. VS Code, Zed, and Sublime Text are detected automatically for `-c` mode.

---

## Server-side setup

The CLI needs the `[cli]` block in your `noosphere.toml`:

```toml
[cli]
token        = "your-secret-token"
allow_push   = true
allow_delete = true
allow_vault  = false
allow_rebuild = false
```

---

## Building from source

Requires [.NET 10 SDK](https://dotnet.microsoft.com/download) and `clang`.

```bash
git clone https://git.kryptomrx.de/krypto/noz-cli
cd noz-cli

# Run without AOT
dotnet run --project NozCli

# Native AOT binary — macOS Apple Silicon
dotnet publish NozCli/NozCli.csproj -r osx-arm64 -c Release

# Run tests
dotnet test NozCli.Tests/NozCli.Tests.csproj -c Release
```

On macOS, AOT linking requires OpenSSL via Homebrew:

```bash
brew install openssl
```

---

## License

[Polyform Noncommercial 1.0.0](LICENSE) — free for personal and non-commercial use.  
Commercial licensing: [bruno.deanoz1@gmail.com](mailto:bruno.deanoz1@gmail.com).