Configuration

For more than one source, or to run the daemon, describe your syncs in a .hrida-oikb.yaml file.

Create the file

The quickest way is the interactive wizard:

bash

hrida-oikb init            # add --force to overwrite an existing file

Or write it by hand in the folder you run OIKB from:

.hrida-oikb.yaml

sources:
  - name: docs
    source: ./docs
    kb-id: 8f3a2b1c-...

  - name: wiki
    source: github:myorg/wiki
    kb-id: 4e7d9a0f-...
    interval: 1h

Then:

bash

hrida-oikb sync                 # sync every entry once
hrida-oikb sync --name wiki     # just one entry (by name or KB ID)
hrida-oikb validate             # check the file
hrida-oikb validate --deep      # also check the API key, URL and that each KB exists

sources is a list

Each entry starts with - and points one source at one Knowledge Base using source: (in the connector syntax) and kb-id:. A map of named sources, or a connector: key, is not supported.

Entry keys

Key	Required	Description
source	✔	What to sync, e.g. ./docs, github:owner/repo, confluence:ENG. See Connectors
kb-id	✔	Target Knowledge Base ID
name		Label used in logs, the dashboard, sync --name and POST /sync/{name}
branch, path		Branch and subfolder for GitHub, GitLab and Bitbucket
interval		Schedule for the daemon: 30m, 1h, or a cron expression. See Scheduling
concurrency		Parallel upload workers
filter		include, exclude, max-size. See Filtering
notify		Webhook to call on failure (or always). See Notifications
webhook		true to let the daemon's webhooks trigger this entry
github_secret, gitlab_secret, slack_signing_secret		Webhook signature secrets
url, token		Override the Hrida.ai URL and API key for this entry, e.g. to sync into a different Hrida.ai instance. These are not connector credentials

token is the Hrida.ai key

Connector credentials such as GITHUB_TOKEN or CONFLUENCE_TOKEN are read from environment variables. Writing token: ${GITHUB_TOKEN} in an entry sends the GitHub token to Hrida.ai as its API key, and the sync fails with 401.

Global defaults

Put shared settings under defaults:. Each entry inherits them; its own values win. Nested settings (filter, notify) are merged key by key.

yaml

defaults:
  interval: 1h
  concurrency: 4
  filter:
    max-size: 50mb
  notify:
    url: https://hooks.slack.com/services/T.../B.../xxx
    on: error

sources:
  - name: docs
    source: github:myorg/docs
    kb-id: abc123

  - name: handbook
    source: confluence:ENG
    kb-id: def456
    interval: "0 6 * * 1-5"   # overrides the default

Environment variables in the file

Every string value can reference environment variables as ${VAR}, or ${VAR:-fallback} for a default. This lets you commit .hrida-oikb.yaml to Git and keep secrets and IDs in the environment:

yaml

sources:
  - name: docs
    source: github:${GITHUB_ORG}/docs
    kb-id: ${KB_DOCS_ID}
    notify:
      url: ${SLACK_WEBHOOK:-https://hooks.slack.com/fallback}

Connector credentials (such as GITHUB_TOKEN or CONFLUENCE_TOKEN) are read straight from the environment, so they don't need to appear in the file at all. See Connectors.

---

Filtering

Include and exclude

yaml

sources:
  - name: docs
    source: github:owner/repo
    kb-id: abc123
    filter:
      include: ["docs/**/*.md", "*.txt"]
      exclude: ["drafts/**", "**/*.tmp"]

• include: only sync files matching these patterns.
• exclude: skip files matching these patterns (applied after include).

Maximum file size

yaml

filter:
  max-size: 50mb      # b, kb, mb, gb

Larger files are skipped with a warning:

⚠ Skipping model.bin (2.1 GB) — exceeds max-size (50.0 MB)

On the command line: --max-file-size 50mb.

.hrida-oikbignore

For local folders, put a .hrida-oikbignore file in the source root. It uses the same patterns as .gitignore.

Splitting a source across Knowledge Bases

Use one entry per Knowledge Base, each with its own include filter:

yaml

sources:
  - name: user-docs
    source: github:owner/repo
    kb-id: abc123
    filter:
      include: ["docs/**"]

  - name: api-reference
    source: github:owner/repo
    kb-id: def456
    filter:
      include: ["api/**"]

---

Upgrading from 0.x

0.x	1.0
sync: top-level key	sources: (old key still read)
kb: / --kb	kb-id: / --kb-id
routes:	Removed: use several entries with filter.include
POST /sync/{source}	POST /sync/{name-or-kb-id}