# Getting Started

Build the `kura` binary, register a database, start the daemon, and run a first keyword search against files you drop in.

## Requirements

| Item | Requirement | Why |
|---|---|---|
| Operating system | macOS (APFS/HFS+) or Linux (ext4/xfs) | The daemon detaches with `setsid` and the watcher relies on POSIX file metadata |
| Go | 1.25.1 or later | `go.mod` declares `go 1.25.1` |
| C toolchain | Any compiler cgo can use | SQLite is accessed through `github.com/mattn/go-sqlite3` |
| `pdftotext` | Only for PDF files (poppler-utils) | PDF text is extracted with `pdftotext -layout -enc UTF-8` |

## Build and Install

```bash
git clone https://github.com/pardnchiu/KuraDB.git
cd KuraDB
make build
```

| Target | Runs |
|---|---|
| `make build` | `go build -o bin/kura ./cmd/app` |
| `make app` | Stop a running daemon, build, move the binary to `/usr/local/bin/kura` with `sudo`, start the daemon |
| `make stop` | `go run ./cmd/app stop` |
| `make test` | `go test -v -count=1 ./...` |
| `make add <name>`, `make list`, `make remove <name>`, `make edit <old> <new>`, `make port <args>`, `make help` | The matching subcommand through `go run ./cmd/app` |

## Register a Database and Start the Daemon

```bash
kura add notes
kura
```

`kura add notes` creates `~/.config/kuradb/notes/inbox/`, links it as `~/Kura_notes`, and records the name in `db.json`. Running `kura` with no arguments forks the daemon into the background and prints its address, for example `http://localhost:21182`.

A database added while the daemon is running is not picked up until the daemon restarts:

```bash
kura stop
kura
```

## Drop Files and Search

```bash
cp ~/Documents/design-notes.md ~/Kura_notes/
curl "$(cat ~/.config/kuradb/endpoint)/api/search?db=notes&q=sqlite"
```

The watcher scans each inbox every 10 seconds, so a new file is searchable within about 10 seconds. The response groups matching paragraphs by source file:

```json
{
  "keyword": [
    {
      "source": "/Users/you/.config/kuradb/notes/inbox/design-notes.md",
      "matches": [
        { "chunk": 2, "content": "Second paragraph about SQLite" }
      ]
    }
  ]
}
```

To let an agent query the same data, register the stdio MCP server with your client, for example in Claude Code:

```bash
claude mcp add kura -- kura mcp
```

## Next Steps

- [Indexing Pipeline](/indexing-pipeline): how dropped files become searchable rows
- [Keyword Search](/keyword-search): how queries are matched and ranked
- [MCP Server](/mcp-server): `list_rag` and `search_rag` for agents
- [CLI Reference](/cli-reference): every `kura` subcommand