Installation & First Sync

Getting access

Knowledge Sync is available to licensed Hrida AI clients only. It is not published on public PyPI or Docker Hub. Your Hrida AI contact gives your GitHub account (or your team) access to:

What	Needed for	How you sign in
The private `Hrida-AI/hrida-oikb` repository (read)	The pip package (wheel) attached to each release	`gh auth login`, or an SSH key on your GitHub account
The private image `ghcr.io/hrida-ai/hrida-oikb` (read)	Docker, Docker Compose, Kubernetes and CI	`docker login ghcr.io` with a token that has the `read:packages` scope

For servers and CI, create a dedicated token with only the scopes it needs (read:packages for the image), store it as a secret, and rotate it like any other credential. Access can be withdrawn per account at any time; your existing installs keep working, but you can't download new releases.

Requirements

Hrida.ai Studio with the knowledge sync API (POST /api/v1/knowledge/{id}/sync/diff). Without it, every sync stops with 405 Method Not Allowed, whatever the API key. To check a Studio, call the endpoint without a key:
bash
```
curl -s -o /dev/null -w "%{http_code}\n" -X POST "$HRIDA_AI_URL/api/v1/knowledge/test/sync/diff"
```
On Windows PowerShell: curl.exe -s -o NUL -w "%{http_code}" -X POST "$env:HRIDA_AI_URL/api/v1/knowledge/test/sync/diff".

401 means the API is there and is asking for a key. 405 means that Studio doesn't have it yet: update Studio first.
An API key of a user who can write to the target Knowledge Base: its owner, someone it is shared with for writing, or an admin.
Python 3.11+ for the pip package, or Docker for the image.

Install

warning

Never run pip install hrida-oikb against public PyPI, and don't confuse it with oikb, an unrelated public package. A package with that name on pypi.org is not from Hrida AI.

Each release has the package attached as a wheel (.whl), together with a SHA256SUMS file. Download both with the GitHub CLI, check the wheel, and install it:

bash

gh release download v1.0.3 -R Hrida-AI/hrida-oikb -p "*.whl" -p SHA256SUMS
sha256sum -c SHA256SUMS          # macOS: shasum -a 256 -c SHA256SUMS
pip install ./hrida_oikb-1.0.3-py3-none-any.whl

The check must print OK. On Windows, compare (Get-FileHash .\hrida_oikb-1.0.3-py3-none-any.whl).Hash with the value in SHA256SUMS. If it doesn't match, don't install the file; download it again or contact Hrida AI.

Or install straight from the repository over SSH:

bash

pip install "hrida-oikb @ git+ssh://git@github.com/Hrida-AI/hrida-oikb.git@v1.0.3"

Replace 1.0.3 with the release you want. Some connectors need extra client libraries. Install only what you use, or everything:

bash

pip install "./hrida_oikb-1.0.3-py3-none-any.whl[s3]"    # one extra
pip install "./hrida_oikb-1.0.3-py3-none-any.whl[all]"   # every optional connector

See Connectors for the list of extras. Requires Python 3.11+.

Prefer containers? Use the private image ghcr.io/hrida-ai/hrida-oikb (amd64 and arm64): sign in with docker login ghcr.io using a GitHub token that can read packages. Image tags match releases without the "v" (:1.0.3, :1.0), plus :latest for the newest release. See Deployment.

Windows: standalone executable (no Python needed)

From v1.0.1, each release also has a self-contained Windows build with every connector included:

File	Use it for
`hrida-oikb-<version>-windows-x64.zip`	Deployment package (recommended): the exe, an installer that puts it on your `PATH`, an example config (`hrida-oikb.example.yaml`) and a quick-start `README.txt`
`hrida-oikb-<version>-windows-x64.exe`	Just the program. Its file name includes the version, so the command is that name unless you rename it to `hrida-oikb.exe`

bash

gh release download v1.0.3 -R Hrida-AI/hrida-oikb -p "*windows-x64.zip" -p SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing      # must print OK

Unzip the whole folder and double-click install.cmd (or run it from a Command Prompt). It copies hrida-oikb.exe to %LOCALAPPDATA%\Programs\hrida-oikb and adds that folder to your user PATH; no administrator rights are needed, and running it again upgrades. Then open a new Command Prompt or PowerShell window (windows that were already open keep the old PATH) and check:

bash

hrida-oikb --version
hrida-oikb config set url https://your-studio.example.com
hrida-oikb config set token sk-...
hrida-oikb sync C:\Docs --kb-id <knowledge-base-id> --dry-run

To install somewhere else, run install.cmd -InstallDir D:\Tools\hrida-oikb. To remove it, run uninstall.cmd from the package folder; your settings and .hrida-oikb.yaml files are kept.

The v1.0.1 and v1.0.2 packages have no installer. With those, add the folder holding hrida-oikb.exe to your PATH yourself (Settings › System › About › Advanced system settings › Environment Variables, under User variables), then open a new window. Or run it from its folder as .\hrida-oikb.exe (PowerShell) or hrida-oikb.exe (Command Prompt).

To keep the daemon running, create a Windows Task Scheduler task that starts hrida-oikb.exe with the argument daemon at startup, using the full path the installer printed (normally C:\Users\<you>\AppData\Local\Programs\hrida-oikb\hrida-oikb.exe), with Start in set to the folder holding .hrida-oikb.yaml. Stop the task before upgrading: a running hrida-oikb.exe can't be replaced.

`'hrida-oikb' is not recognized as an internal or external command`

Windows can't find hrida-oikb on your PATH:

Windows package: run install.cmd from the unzipped folder, then use a window opened after it. Unzipping alone doesn't put anything on PATH.
Standalone .exe download: its name includes the version (hrida-oikb-1.0.3-windows-x64.exe). Rename it to hrida-oikb.exe and add its folder to PATH, or use the package's installer instead.
pip install: see the next section.

`hrida-oikb: command not found` after installing

pip installed the package, but the folder it puts the hrida-oikb command in isn't on your PATH. This is common on Windows (including Git Bash), with pip install --user, and with Python from the Microsoft Store. pip warns about it during the install: "The script hrida-oikb.exe is installed in '…\Scripts' which is not on PATH".

Any one of these fixes it:

Run it through Python. This always works, wherever pip put the command:

bash

python -m hrida_oikb --help          # Windows launcher: py -m hrida_oikb --help

Install it as a tool (recommended for regular use). uv or pipx puts hrida-oikb in its own environment and on your PATH:
bash
```
uv tool install ./hrida_oikb-1.0.3-py3-none-any.whl     # then: uv tool update-shell
pipx install ./hrida_oikb-1.0.3-py3-none-any.whl        # then: pipx ensurepath
```
Add an extra the same way, for example "./hrida_oikb-1.0.3-py3-none-any.whl[s3]". Open a new terminal afterwards.
Add pip's scripts folder to PATH. Print it with:
bash
```
python -c "import sysconfig; print(sysconfig.get_path('scripts'))"            # normal install
python -c "import sysconfig, os; print(sysconfig.get_path('scripts', f'{os.name}_user'))"   # pip install --user
```
Then add that folder to PATH: on Windows in Settings › System › About › Advanced system settings › Environment Variables, or for the current Git Bash session with export PATH="$PATH:$(cygpath -u '<folder>')".

Connect to Hrida.ai

OIKB needs your Hrida.ai URL and an API key that can write to the target Knowledge Bases (create one under Settings → Account → API keys).

Option A: environment variables

bash

export HRIDA_AI_URL=http://localhost:3000
export HRIDA_AI_API_KEY=sk-your-api-key

Option B: save them once

bash

hrida-oikb config set url http://localhost:3000
hrida-oikb config set token sk-your-api-key
hrida-oikb config get        # shows the saved values (key is masked)

Saved values go to ~/.config/hrida-oikb/config.yaml. If a value is set in more than one place, this order applies (highest first):

CLI flags: --url, --token
Environment variables: HRIDA_AI_URL, HRIDA_AI_API_KEY
The saved config file

Find your Knowledge Base ID

In Hrida.ai, open Knowledge, click the Knowledge Base, and copy the ID from the URL:

http://localhost:3000/knowledge/8f3a2b1c-1234-5678-9abc-def012345678
                                └──────────── KB ID ───────────────┘

Check it with:

bash

hrida-oikb status --kb-id 8f3a2b1c-...

Your first sync

Preview first. A dry run shows what would be added, modified and deleted without touching the Knowledge Base:

bash

hrida-oikb sync ./docs --kb-id your-kb-id --dry-run

Then sync for real:

bash

hrida-oikb sync ./docs --kb-id your-kb-id

Run the same command again and nothing is uploaded: only new and modified files are sent.

Deletions follow the source

A sync makes the Knowledge Base match the source. Files you delete at the source are deleted from the Knowledge Base too, including files that were added to it some other way. Use a dedicated Knowledge Base per source (or split one source across several), and use --dry-run when in doubt.

Useful flags:

Flag	Purpose
`--dry-run`	Preview only
`--concurrency 4`	Upload with 4 parallel workers (default 1)
`--max-file-size 50mb`	Skip larger files
`--branch develop` / `--path docs/`	Branch and subfolder for GitHub, GitLab and Bitbucket
`-v`	Verbose progress

Watch a folder

Keep a local folder in sync as you edit:

bash

hrida-oikb watch ./docs --kb-id your-kb-id

It reacts to filesystem events (no polling) and waits until changes settle, 1 second by default (--debounce 2.0 to change it).

Next steps

Several sources, schedules or webhooks: Configuration → and Daemon →
Sync something other than a folder: Connectors →

Getting access​

Requirements​

Install​

Windows: standalone executable (no Python needed)​

'hrida-oikb' is not recognized as an internal or external command​

hrida-oikb: command not found after installing​

Connect to Hrida.ai​

Find your Knowledge Base ID​

Your first sync​

Watch a folder​

Next steps​

Getting access

Requirements

Install

Windows: standalone executable (no Python needed)

`'hrida-oikb' is not recognized as an internal or external command`

`hrida-oikb: command not found` after installing

Connect to Hrida.ai

Find your Knowledge Base ID

Your first sync

Watch a folder

Next steps