Skip to content

docs: add database schema, CLI reference, and repository API docs #333

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
d-oit merged 1 commit into from
Jun 19, 2026
+523 −382
Merged

docs: add database schema, CLI reference, and repository API docs #333

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
271 changes: 79 additions & 192 deletions docs/CLI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,239 +1,168 @@
# CLI Reference

The `knowledge-studio` CLI provides terminal-based automation for managing your knowledge base. It uses the same repository layer as the browser app but runs in Node.js via `better-sqlite3`.
Command-line interface for Knowledge Studio. Run with `pnpm run cli -- <command>`.

## Global Options

| Flag | Description | Default |
|------|-------------|---------|
| `--db-path <path>` | Custom path to SQLite database file | `~/.local/share/do-knowledge-studio/data.db` |
| `--version` | Show version number | — |
| `--help` | Show help for any command | — |

Run any command with `pnpm run cli -- <command> [args] [options]`.

---

## Commands

### `init`

Initialize the workspace. Creates the `./export` directory if it doesn't exist.

```bash
pnpm run cli -- init
```

---

### `sync <source>`

Sync data from a directory of Markdown files or a URL into the database.

**Arguments:**
- `<source>` — Directory path or HTTP(S) URL

**From a directory:** Reads all `.md` files. The first H1 heading becomes the entity name. Entities are created as type `concept`.

```bash
pnpm run cli -- sync ./path/to/markdown/files
```

**From a URL:** Fetches content via Jina AI reader (cross-origin) or direct fetch (same-origin). Creates an entity with the page title and content.

```bash
pnpm run cli -- sync https://example.com/article
```

---

### `export`

Export the knowledge base to various formats.

**Options:**

| Flag | Description | Default |
|------|-------------|---------|
| `-f, --format <format>` | Export format: `md`, `json`, or `site` | `md` |
| `-o, --output <dir>` | Output directory | `./export` |

```bash
# Markdown — one file per entity
pnpm run cli -- export --format md --output ./export/markdown

# JSON — single knowledge.json file
pnpm run cli -- export --format json --output ./export/json

# Static site — portable HTML file
pnpm run cli -- export --format site --output ./export/site
```

---

### `search <query>`

Full-text search across entities using FTS5.

```bash
pnpm run cli -- search "artificial intelligence"
```

---
## Entity Commands

### `entity-create <name>`

Create a new entity.

**Options:**

| Flag | Description | Default |
|------|-------------|---------|
| `-t, --type <type>` | Entity type | `concept` |
| `-d, --description <text>` | Entity description | — |
| `-u, --source-url <url>` | Source URL for auto-hydration | — |

```bash
pnpm run cli -- entity-create "TRIZ" --type concept --description "Theory of Inventive Problem Solving"

# Auto-hydrate description from URL
pnpm run cli -- entity-create "TRIZ" --source-url https://en.wikipedia.org/wiki/TRIZ
pnpm run cli -- entity-create "TRIZ" -t concept -d "Theory of Inventive Problem Solving"
```

---
| Option | Description | Default |
|--------|-------------|---------|
| `-t, --type <type>` | Entity type | `concept` |
| `-d, --description <description>` | Entity description | |
| `-u, --source-url <url>` | Source URL for auto-hydration | |

### `entity-list`

List all entities in the database.
List all entities.

```bash
pnpm run cli -- entity-list
```

Output: `[type] name` per line.

---

### `entity-get <name>`

Get detailed information about an entity by name.
Get entity details by name.

```bash
pnpm run cli -- entity-get "TRIZ"
```

---

### `entity-update <name>`

Update an entity's type or description.

**Options:**

| Flag | Description |
|------|-------------|
| `-t, --type <type>` | New entity type |
| `-d, --description <text>` | New description |

```bash
pnpm run cli -- entity-update "TRIZ" --type methodology --description "Updated description"
pnpm run cli -- entity-update "TRIZ" -d "Updated description"
```

---
| Option | Description |
|--------|-------------|
| `-t, --type <type>` | New entity type |
| `-d, --description <description>` | New description |

### `entity-delete <name>`

Delete an entity and all its cascading data (claims, notes, links).
Delete an entity and cascade (claims, links, notes).

```bash
pnpm run cli -- entity-delete "Old Entity"
pnpm run cli -- entity-delete "TRIZ"
```

---
## Claim Commands

### `claim-create <entity-name> <statement>`

Create a claim (assertion) about an entity.
Create a claim for an entity.

**Options:**
```bash
pnpm run cli -- claim-create "TRIZ" "TRIZ has 40 inventive principles" -c 0.95
```

| Option | Description | Default |
|--------|-------------|---------|
| `-c, --confidence <confidence>` | Confidence score (0–1) | `1.0` |

| Flag | Description | Default |
|------|-------------|---------|
| `-c, --confidence <value>` | Confidence score (0.0–1.0) | `1.0` |
## Note Commands

### `note-create <entity> <content>`

Create a note for an entity.

```bash
pnpm run cli -- claim-create "TRIZ" "TRIZ was developed by Genrich Altshuller" --confidence 0.95
pnpm run cli -- note-create "TRIZ" "Key insight: separation principles"
```

---
### `note-list <entity>`

### `link-create <source> <target>`
List notes for an entity.

Create a relationship link between two entities.
```bash
pnpm run cli -- note-list "TRIZ"
```

## Link Commands

**Options:**
### `link-create <source> <target>`

| Flag | Description | Default |
|------|-------------|---------|
| `-r, --relation <type>` | Relation type | `related` |
Create a directed link between two entities.

```bash
pnpm run cli -- link-create "TRIZ" "Genrich Altshuller" --relation "created_by"
pnpm run cli -- link-create "TRIZ" "Innovation" -r "inspires"
```

---
| Option | Description | Default |
|--------|-------------|---------|
| `-r, --relation <relation>` | Relation type | `related` |

### `link-list`

List all links in the database.
List all links with resolved entity names.

```bash
pnpm run cli -- link-list
```

Output: `[id] source --[relation]--> target` per line.

---

### `link-delete <id>`

Delete a link by its ID.
Delete a link by ID.

```bash
pnpm run cli -- link-delete <link-id>
pnpm run cli -- link-delete "abc-123"
```

---
## Search Commands

### `note-create <entity> <content>`
### `search <query>`

Create a note attached to an entity.
Full-text search entities using FTS5.

```bash
pnpm run cli -- note-create "TRIZ" "Key insight: contradictions drive innovation"
pnpm run cli -- search "inventive principles"
```

---
### `snapshot-list`

### `note-list <entity>`
List all graph snapshots.

```bash
pnpm run cli -- snapshot-list
```

## Export Commands

### `export`

List all notes for an entity.
Export knowledge base data.

```bash
pnpm run cli -- note-list "TRIZ"
pnpm run cli -- export -f md -o ./export
pnpm run cli -- export -f json -o ./export
pnpm run cli -- export -f site -o ./export
pnpm run cli -- export -f pdf -o ./export
```

---
| Option | Description | Default |
|--------|-------------|---------|
| `-f, --format <format>` | Export format: `md`, `json`, `site`, `pdf` | `md` |
| `-o, --output <dir>` | Output directory | `./export` |

### `snapshot-list`
### `import <file>`

List all saved graph snapshots.
Import from JSON or Markdown file.

```bash
pnpm run cli -- snapshot-list
pnpm run cli -- import knowledge.json
pnpm run cli -- import notes.md
```

---
## Database Commands

### `db:migrate`

Expand All @@ -243,68 +172,26 @@ Run pending database migrations.
pnpm run cli -- db:migrate
```

---

### `db:rollback`

Roll back the last applied migration.
Rollback the last applied migration.

```bash
pnpm run cli -- db:rollback
```

---

### `db:status`

Show the status of all migrations (applied or pending).
Show migration status for all migrations.

```bash
pnpm run cli -- db:status
```

---

### `db:backup [path]`

Create a backup of the SQLite database using `VACUUM INTO`.

```bash
pnpm run cli -- db:backup # Default: .studio-cli-backup-<timestamp>.db
pnpm run cli -- db:backup ./backups/my.db # Custom path
```

---

### `db:reset`

**Destructive.** Drop all tables and re-run the schema from scratch.
Reset database (drop all tables and re-run schema). **Destructive operation.**

```bash
pnpm run cli -- db:reset
```

---

## Sharing Data Between CLI and Browser

To see CLI-created data in the browser app:

1. Open the app in Chrome or Edge
2. Go to **AI Harness** → click the **Settings** (gear) icon
3. Click **Connect Local Database**
4. Select the database directory (usually `~/.local/share/do-knowledge-studio/`)
5. Reload the page when prompted

The browser synchronizes its OPFS storage with the `data.db` file in that directory.

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `Database not initialized` | Ensure `--db-path` points to a valid SQLite file, or run `init` first |
| `Entity not found` | Use `entity-list` to verify the entity name (case-sensitive) |
| `Sync found 0 files` | Ensure the directory contains `.md` files with H1 headings |
| `Backup failed` | Check write permissions for the output directory |
Loading
Loading