Nb

# nb - Command Line Note-Taking

> ⚠️ **IMPORTANT:** Never edit files in nb git repos (`~/.nb/*`) by hand! Always use the `nb` CLI to ensure proper indexing and Git commits.

A command line and local web note-taking, bookmarking, and archiving tool with plain text data storage, Git-backed versioning, and wiki-style linking.

## Quick Reference

### Notebooks

```bash # List all notebooks nb notebooks

# Switch to a notebook nb use <notebook>

# Create a new notebook nb notebooks add <name>

# Show current notebook nb notebooks current ```

### Adding Notes

```bash # Add a note with title nb add -t "Title" -c "Content here"

# Add note to specific notebook nb <notebook>: add -t "Title" -c "Content"

# Add note with tags nb add -t "Title" --tags tag1,tag2

# Add note from file content nb add <notebook>:filename.md ```

### Listing Notes

```bash # List notes in current notebook nb list

# List all notes (no limit) nb list -a

# List notes in specific notebook nb <notebook>: list

# List with excerpts nb list -e

# List with tags shown nb list --tags ```

### Showing Notes

```bash # Show note by ID or title nb show <id> nb show "<title>"

# Show note from specific notebook nb show <notebook>:<id>

# Print content (for piping) nb show <id> --print ```

### Searching Notes

```bash # Search across all notebooks nb search "query"

# Search in specific notebook nb <notebook>: search "query"

# Search with AND/OR/NOT nb search "term1" --and "term2" nb search "term1" --or "term2" nb search "term1" --not "exclude"

# Search by tag nb search --tag "tagname" ```

### Editing Notes

```bash # Edit by ID nb edit <id>

# Edit by title nb edit "<title>"

# Append content nb edit <id> -c "New content to append"

# Prepend content nb edit <id> -c "Content at top" --prepend

# Overwrite content nb edit <id> -c "Replace all" --overwrite ```

### Deleting Notes

```bash # Delete by ID (will prompt) nb delete <id>

# Force delete without prompt nb delete <id> -f ```

### Moving/Renaming

```bash # Move note to another notebook nb move <id> <notebook>:

# Rename a note nb move <id> new-filename.md ```

### Todos

```bash # Add a todo nb todo add "Task title"

# Add todo with due date nb todo add "Task" --due "2026-01-15"

# List open todos nb todos open

# List closed todos nb todos closed

# Mark todo as done nb todo do <id>

# Mark todo as not done nb todo undo <id> ```

### Bookmarks

```bash # Add a bookmark nb bookmark <url>

# Add with comment nb bookmark <url> -c "My comment"

# Add with tags nb bookmark <url> --tags reference,dev

# List bookmarks nb bookmark list

# Search bookmarks nb bookmark search "query" ```

### Git Operations

```bash # Sync with remote nb sync

# Create checkpoint (commit) nb git checkpoint "Message"

# Check dirty status nb git dirty

# Run any git command nb git status nb git log --oneline -5 ```

### Folders

```bash # Add folder to notebook nb folders add <folder-name>

# List folders nb folders

# Add note to folder nb add <folder>/<filename>.md ```

## Common Patterns

### Adding Note with Full Content

For longer notes, create a temp file and import:

```bash # Write content to temp file first, then copy to nb cp /tmp/note.md ~/.nb/<notebook>/ cd ~/.nb/<notebook> && git add . && git commit -m "Add note" nb <notebook>: index rebuild ```

### Searching Across All

```bash # Search everything nb search "term" --all

# Search by type nb search "term" --type bookmark nb search "term" --type todo ```

## Data Location

Notes are stored in `~/.nb/<notebook>/` as markdown files with Git versioning.

``` ~/.nb/ ├── notebook-name-1/ # Your first notebook ├── notebook-name-2/ # Your second notebook └── ... ```

## Tips

1. Use `nb <notebook>:` prefix to work with specific notebooks 2. IDs are numbers shown in `nb list` 3. Titles can be used instead of IDs (quoted if spaces) 4. All changes are automatically Git-committed 5. Use `nb sync` to push/pull from remote repos