Big News: Socket raises $60M Series C at a $1B valuation to secure software supply chains for AI-driven development.Announcement →
Sign In

llmwiki-cli

Package Overview
Dependencies
Maintainers
1
Versions
11
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

llmwiki-cli - npm Package Compare versions

Comparing version
0.2.3
 to
0.3.1
dist/index.js

Sorry, the diff of this file is too big to display

+5
-5
package.json
{
"name": "llmwiki-cli",
"version": "0.2.3",
"version": "0.3.1",
"description": "CLI tool for LLM agents to build and maintain personal knowledge bases",

@@ -12,4 +12,4 @@ "repository": {

"bin": {
"wiki": "dist/wiki.js",
"llmwiki": "dist/wiki.js"
"wiki": "dist/index.js",
"llmwiki": "dist/index.js"
},

@@ -20,4 +20,4 @@ "files": [

"scripts": {
"build": "bun build bin/wiki.ts --outfile dist/wiki.js --target node",
"dev": "bun run bin/wiki.ts",
"build": "bun build src/index.ts --outfile dist/index.js --target node",
"dev": "bun run src/index.ts",
"test": "bun test",

@@ -24,0 +24,0 @@ "typecheck": "bunx tsc --noEmit",

+32
-61
README.md

@@ -5,2 +5,3 @@ # llmwiki-cli

![total downloads](https://img.shields.io/npm/dt/llmwiki-cli)
![Visitors](https://visitor-badge.laobi.icu/badge?page_id=doum1004.llmwiki-cli)
[![CI](https://img.shields.io/github/actions/workflow/status/doum1004/llmwiki-cli/ci.yml?branch=main&style=flat-square&label=CI&logo=github)](https://github.com/doum1004/llmwiki-cli/actions/workflows/ci.yml)

@@ -25,5 +26,5 @@ [![license](https://img.shields.io/npm/l/llmwiki-cli?style=flat-square&color=blue)](./LICENSE)

| shells out to:
| $ wiki init my-wiki --domain "machine learning"
| $ wiki write wiki/concepts/attention.md <<'EOF' ... EOF
| $ wiki index add "concepts/attention.md" "Overview of attention"
| $ wiki init my-wiki --name "Notes" --domain "machine learning"
| $ wiki write wiki/concepts/attention.md --from-frontmatter --log-type ingest <<'EOF' ... EOF
| $ wiki index remove "concepts/old.md" # when needed; see wiki skill
| $ wiki search "scaling laws"

@@ -33,10 +34,9 @@ | $ wiki lint

v
wiki CLI (StorageProvider abstraction)
|
v
filesystem | git (auto-commit + auto-push)
wiki CLI (StorageProvider → local markdown files)
```
**Key principle**: The CLI never calls any LLM API. It is a pure storage tool with pluggable backends.
**Key principle**: The CLI never calls any LLM API. It reads and writes markdown on disk only (no built-in Git sync or cloud backends).
**AI assistants / coding agents:** Use [CLAUDE.md](CLAUDE.md) for instructions, rules, and technical context. This README stays oriented to people (overview, install, usage).
## Install

@@ -50,20 +50,10 @@

## Storage Backends
| Backend | Description | Init |
|---------|-------------|------|
| `filesystem` (default) | Plain markdown files on disk | `wiki init my-wiki` |
| `git` | Filesystem + auto-commit + auto-push to GitHub | `wiki init my-wiki --backend git --git-token <pat>` |
## Quick Start
```bash
# Create a new wiki (filesystem backend, default)
# Create a new wiki
wiki init my-wiki --name "My Notes" --domain "research"
# Or with git + GitHub sync
wiki init my-wiki --name "My Notes" --domain "research" --backend git --git-token ghp_xxx
# Write a page
wiki write wiki/concepts/attention.md <<'EOF'
# Write a page and sync index + log from YAML title (recommended when you have frontmatter)
wiki write wiki/concepts/attention.md --from-frontmatter --log-type ingest <<'EOF'
---

@@ -78,5 +68,3 @@ title: Attention Mechanism

# Add to index and log
wiki index add "concepts/attention.md" "Overview of attention mechanisms"
wiki log append ingest "Attention mechanism page"
# Still use wiki index / wiki log for removals, show, log-only events (queries, maintenance), etc.

@@ -90,16 +78,8 @@ # Search and lint

When you run `wiki init` (filesystem or git backend), it creates:
When you run `wiki init`, it creates:
```
my-wiki/
├── .git/ # Only with --backend git
├── .github/ # Only with --backend git (--viz)
│ └── workflows/
│ └── wiki-viz.yml # GitHub Actions → GitHub Pages visualization
├── .gitignore # Only with --backend git (--viz)
├── .llmwiki.yaml # Wiki config (all backends)
├── .llmwiki.yaml # Wiki config
├── SCHEMA.md # Instructions for LLM agents
├── scripts/ # Only with --backend git (--viz)
│ ├── build-graph.js # Builds graph.json from wikilinks
│ └── build-site.js # Generates d3-force visualization
├── raw/ # Immutable source documents

@@ -116,2 +96,4 @@ │ └── assets/ # Downloaded images

Use normal Git in `my-wiki/` if you want version control. The CLI does not run `git init` for you.
**Storage profiles:** `wiki profile use <slug>`, `--profile`, `LLMWIKI_PROFILE`, or top-level `profile` in `.llmwiki.yaml`. Pages live under `profiles/<slug>/` inside the wiki directory. This is organizational separation only, not OS or cryptographic isolation.

@@ -123,6 +105,3 @@

```bash
wiki init [dir] --name <name> --domain <domain> --backend <type>
wiki init [dir] --backend git --git-token <pat> [--git-repo owner/repo]
wiki init [dir] --backend git --no-viz # Skip visualization scaffolding
wiki init [existing-wiki-dir] --viz # Add visualization to existing git wiki
wiki init [dir] --name <name> --domain <domain> # Create wiki (local files only)
wiki registry # List all wikis

@@ -138,3 +117,3 @@ wiki use [wiki-id] # Set active wiki

wiki read <path> # Print page to stdout
wiki write <path> # Write stdin to page
wiki write <path> [--index-summary …] [--log-type … [--log-message …]] [--from-frontmatter] # stdin; optional index + log; title from YAML when flag set
wiki append <path> # Append stdin to page

@@ -165,3 +144,3 @@ wiki list [dir] [--tree] [--json] # List pages

Run `wiki skill` to print the full guide, or see [`docs/SKILL.md`](docs/SKILL.md) for the source. Covers workflows, command patterns, page format, and common gotchas for LLM agents.
Run `wiki skill` to print the full guide. The canonical text lives in [`src/commands/skill.ts`](src/commands/skill.ts) (`SKILL_GUIDE`); update it when commands change. Covers workflows, command patterns, page format, and common gotchas for LLM agents.

@@ -211,22 +190,15 @@ ## How LLM Agents Use This

## Git backend and GitHub
## Optional: link graph on GitHub Pages
- **New repo:** With `--git-token` and no `--git-repo`, the CLI creates **`wiki-<name>` as a public repository** (straightforward to try GitHub Pages). Use `--git-repo owner/existing` to target a repo you already manage.
- **Token not committed:** `.llmwiki.yaml` stores **`git.repo` only**, not your PAT, so GitHub’s push secret scanning does not reject commits. For **`wiki write` / `wiki append`** (auto-push), set **`LLMWIKI_GIT_TOKEN`**, **`GITHUB_TOKEN`**, or **`GIT_TOKEN`** in your environment.
- **PAT permissions:** The token must be allowed to update **GitHub Actions workflow** files (classic PAT: include the **`workflow`** scope; fine-grained: grant workflow/Actions write). Otherwise the first push after init can fail on `.github/workflows/wiki-viz.yml`.
The CLI does **not** scaffold Git or Actions during `wiki init`. If you want the same interactive d3-force graph as the [live demo](https://doum1004.github.io/llmwiki-cli/):
## Graph Visualization
1. Initialize or clone a **git** repository at your wiki root (`git init`, add remote, etc.).
2. Copy from **this repository** into your wiki root:
- `.github/workflows/wiki-viz.yml` — source string: `getVizWorkflow()` in [`src/lib/templates.ts`](src/lib/templates.ts)
- `scripts/build-graph.js` and `scripts/build-site.js` — `getBuildGraphScript()` / `getBuildSiteScript()` in the same file
Maintainers can regenerate standalone copies with `bun scripts/generate-viz-scripts.ts [outDir]` (writes `build-graph.cjs` / `build-site.cjs`; rename to `.js` if you prefer).
3. Commit and push. In the GitHub repo, enable **Pages** with source **GitHub Actions**.
Git-backend wikis automatically include a GitHub Actions workflow that builds an interactive d3-force graph visualization of your wiki's link structure and deploys it to GitHub Pages.
The workflow parses `[[wikilinks]]` on each push and publishes the graph site.
- **Auto-scaffolded**: `wiki init --backend git` creates `.github/workflows/wiki-viz.yml` and `scripts/` build scripts by default
- **On every push**: GitHub Actions parses all `[[wikilinks]]`, builds a force-directed graph, and deploys to Pages
- **Interactive**: color-coded nodes by directory, zoom/pan, click-to-highlight connections, hover tooltips
- **Opt-out**: use `--no-viz` to skip visualization scaffolding
- **Add to existing wiki**: re-run `wiki init <dir> --viz` on an existing git wiki to add visualization files
After a successful first push, init also tries to enable **GitHub Pages** (build: GitHub Actions). You can still configure it under **Settings → Pages → Source: GitHub Actions** if needed.
**Branch name:** New git wikis rename the default branch to **`main`** before the first push so the **`github-pages`** Actions environment (which often only allows `main`) accepts deployment. If you see *“Branch master is not allowed to deploy to github-pages”*, rename locally with `git branch -M main`, push `main`, and under **Settings → General** set the **default branch** to `main` (and optionally delete the old `master` branch on GitHub).
## Multi-Wiki Support

@@ -250,3 +222,2 @@

- Node.js >= 18 (or Bun)
- Git (for `--backend git` only)

@@ -259,10 +230,10 @@ ## Development

bun install
bun test # 194 tests
bun run build # bundle to dist/wiki.js
bun test # run full test suite
bun run build # bundle to dist/index.js
bun run dev -- --help
```
## DATA
## Star History
![Visitors](https://visitor-badge.laobi.icu/badge?page_id=doum1004.llmwiki-cli)
[![Star History Chart](https://api.star-history.com/svg?repos=doum1004/llmwiki-cli&type=Date)](https://star-history.com/#doum1004/llmwiki-cli&Date)

@@ -269,0 +240,0 @@ ## License

dist/wiki.js

Sorry, the diff of this file is too big to display