mystuff-cli

Capture, organise, and retrieve personal knowledge—directly from your terminal.

---

mystuff‑cli is a single‑binary command‑line toolkit that saves links, notes, meetings, journals, lists, and self‑evaluations in version‑controlled plain‑text files. No databases, no lock‑in—just your data, under Git.

Quick start

# Install (recommended)
pipx install mystuff-cli

# Initialise workspace
mystuff init                  # creates ~/.mystuff

# First bookmark
mystuff link add --url https://python.org
mystuff link search python    # locate saved links

Key features

• Comprehensive toolkit – links, journal, meetings, wiki, lists, self‑evals, learning materials.
• Plain‑text storage – JSONL / Markdown / YAML; ideal for Git workflows.
• Editor integration – honours $EDITOR and $PAGER.
• Web viewer – open lessons as beautifully styled HTML in your browser.
• Static site generator – create elegant portfolio websites from your data.
• fzf support – interactive selection where available.
• Full‑text search – across every module.
• GitHub stars importer – capture starred repositories as bookmarks.
• Configurable sync – run user‑defined shell commands for backup or deployment.

(Command reference available in /docs/CLI.md.)

Installation

# pipx
pipx install mystuff-cli

# From source
git clone https://github.com/jepemo/mystuff-cli.git
cd mystuff-cli
pip install -e .

Optional tools

Tool	Purpose
fzf	Interactive pickers for list/edit tasks
ripgrep	Faster recursive search (auto‑detected)

Directory structure

~/.mystuff/
├── links.jsonl           # bookmarks & repositories
├── journal/2025‑07‑28.md
├── meeting/2025/standup.md
├── wiki/elixir‑patterns.md
├── lists/reading.yaml
├── learning/
│   ├── lessons/          # your learning materials (markdown)
│   └── metadata.yaml     # progress tracking
└── config.yaml

All data is stored as plain text for transparency and portability.

Learning Management

The learn module helps you track and study educational materials:

# List all lessons
mystuff learn list

# Start a lesson
mystuff learn start python/01-variables.md

# Open current lesson in web browser (opens configured web URL)
mystuff learn current --web

# Complete and move to next lesson
mystuff learn next --web

# View your progress
mystuff learn stats

The --web option opens your lesson in the default browser using the URL configured in config.yaml under generate.web.url. This allows you to view your generated static website with syntax highlighting, responsive design, and your custom theme.

Static Website Generation

Generate a beautiful static website from your mystuff data with automatic GitHub integration:

# Generate with default settings
mystuff generate web

# Generate to specific directory
mystuff generate web --output ~/my-website

# Force overwrite without confirmation
mystuff generate web --force

# Preview the generated site
open ~/my-website/index.html

Configure the website in ~/.mystuff/config.yaml:

generate:
  web:
    output: "~/mystuff_web"
    title: "My Knowledge Base"
    description: "Personal knowledge management"
    author: "Your Name"
    github_username: "yourusername" # Required for GitHub integration
    repositories: # List of repos to display (in order)
      - "repo-name-1"
      - "repo-name-2"
      - "repo-name-3"
    menu_items:
      - name: "GitHub"
        url: "https://github.com/yourusername"
      - name: "Blog"
        url: "/blog"
      - name: "Contact"
        url: "mailto:your@email.com"

Features:

• Elegant jepemo.github.io-inspired design – Minimal, professional aesthetic
• Roboto Mono typography – Clean, readable monospace font
• Dot pattern background – Subtle visual texture (#F5F5F0 beige)
• GitHub integration – Display your chosen repositories with automatic data fetching
• User-controlled repo list – Specify exactly which repos to show and in what order
• Sidebar navigation – Configurable menu with hover states (#558ad8 blue accent)
• Responsive layout – Mobile-friendly design
• No authentication required – Uses public GitHub REST API
• Force mode – Use -f flag to skip overwrite confirmation

The GitHub integration fetches repository details for each repo in your list and displays:

• Repository name (clickable link)
• Description
• Primary programming language

Repositories are shown in the exact order you specify in the config.

Example: See jepemo.github.io for the visual reference.

Syncing

Define any shell commands under sync.commands in config.yaml:

sync:
  commands:
    - git add .
    - git commit -m "sync $(date)"
    - rsync -av ~/.mystuff /backup/mystuff

Execute them with:

mystuff sync run --verbose

Roadmap

Version	Status	Theme
v0.7	Current	Custom sync commands
v1.0	Planned	Stable public API

Full roadmap: /docs/PLAN.md.

License

MIT License.

---