270 lines
6.4 KiB
Markdown
270 lines
6.4 KiB
Markdown
# 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.deanoz@protonmail.com](mailto:bruno.deanoz@protonmail.com).
|