push

Push documentation files to Knoku for indexing.


npx @knoku/cli@latest push
# or, if installed globally
knoku push

What it does

Scans the docs directory: finds all .md, .mdx, and .rst files under KNOKU_DOCS_DIR.
Computes checksums: calculates a SHA-256 hash for each file.
Checks for changes: sends checksums to the API. The backend compares them against stored hashes and returns which files changed or were deleted.
Uploads changed files: sends file content in batches of 10 to the backend for indexing.
Deletes removed files: notifies the backend about files that no longer exist locally.
Computes URL paths: resolves the site URL for each file (frontmatter url: > KNOKU_URL_BASE > framework adapter > fallback; used for widget citation links). See URL path mapping.

If nothing changed since the last push, the CLI prints “Everything is up to date.” and exits.

Automatic exclusions

The following directories are always excluded:

node_modules/
.git/
.knoku/

Additional patterns from KNOKU_EXCLUDE are applied on top. See Configuration for details.

Change detection

The CLI never re-uploads unchanged files. On each push:

Local checksums are sent to POST /api/v1/ingest/check-changes
The backend returns two lists: changed (new or modified) and deleted (removed locally)
Only changed files are uploaded; deleted files are removed from the index

This keeps pushes fast and avoids unnecessary re-indexing.

URL path mapping

Each file gets a url_path field that the chat widget uses to link citations back to the correct page on your site. The CLI resolves this path in priority order:

Frontmatter url:, per-file override.
```
---
url: /widget/install/
---
```
KNOKU_URL_BASE env, project-wide prefix that replaces the adapter routing.
Framework adapter default, auto-detected (Docusaurus adds /docs/, MkDocs adds a trailing slash, Sphinx uses .html, etc.).
Generic fallback: /<path-without-extension> when no framework is detected.

Run knoku doctor to preview the resolved URLs for a sample of files before pushing. See Configuration → URL routing for the override details and Integrations for per-framework adapter mapping.

CI / CD usage

Run push after your docs build step to keep the index up to date on every merge:


# GitHub Actions example
- name: Push docs to Knoku
  env:
    KNOKU_API_KEY: ${{ secrets.KNOKU_API_KEY }}
    KNOKU_PROJECT_ID: ${{ secrets.KNOKU_PROJECT_ID }}
    KNOKU_API_URL: https://api.knoku.com
    KNOKU_DOCS_DIR: ./docs
  run: npx @knoku/cli@latest push

No init step is needed in CI; set the environment variables directly.

Example output


Found 24 files in /Users/you/project/docs
8 files to upload, 2 deleted
  Uploading batch 1... done
  Deleting 2 removed files... done

Done! 8 files pushed, 2 files deleted, indexing started.

When everything is already synced:


Found 24 files in /Users/you/project/docs
Everything is up to date.