--- title: 'flexkit knowledge' description: 'Add, search, download and attach the documents the Flexkit agent uses as sources.' --- # `flexkit knowledge` Manages the project's knowledge: documents (PDF, Word, PowerPoint, Markdown, text, HTML) and web pages that the agent searches and cites. Flexkit extracts each document into passages and indexes them for semantic and keyword search. You can attach a document to a record, or to every record of an entity type, so the agent prefers it when it works on those records. ## Synopsis ```bash flexkit knowledge [arguments] [options] ``` Running `flexkit knowledge` without a subcommand runs `flexkit knowledge ls`. ## `knowledge ls` List the documents you can read, newest first. ```bash flexkit knowledge ls [--search ] [--status ] [--limit ] [--offset ] [--json] ``` ### Examples ```bash # List documents flexkit knowledge ls # Documents whose title or content mentions returns flexkit knowledge ls --search "return policy" # Ids of the documents that failed to index flexkit knowledge ls --status failed --json | jq -r '.sources[].id' ``` ## `knowledge inspect` Show a document: type, size, status, passage count, who can read it, whether the agent can search it, the latest indexing job, and the records and entity types it is attached to. Alias: `get`. ```bash flexkit knowledge inspect [--json] ``` ### Examples ```bash # Show a document flexkit knowledge inspect 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f # Print the indexing error, if any flexkit knowledge inspect 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --json | jq -r '.source.currentVersion.error' ``` ## `knowledge add` Add files, folders and `https://` web pages. Files are uploaded straight to the Flexkit file store, then indexed in the background. Folders are walked recursively; hidden files and `node_modules` are ignored, and files of other types (images, spreadsheets…), empty files and files over 20 MB are skipped with a warning. Adding a file that is already in the project returns the existing document (`already added`). Alias: `upload`. With `--wait`, the command follows indexing until every document is ready or failed, and exits with code 1 if any failed. With `--link`, every added document is attached to the given record or entity type. ```bash flexkit knowledge add [--title ] [--space <code>...] [--hide-from-agent] [--link <entity[:recordId]>...] [--concurrency <n>] [--wait] [--timeout <seconds>] [--json] ``` ### Examples ```bash # Add a PDF and wait until the agent can search it flexkit knowledge add ./handbook.pdf --wait # Add a folder of documents, five uploads at a time flexkit knowledge add ./docs/policies --concurrency 5 # Add a web page with your own title flexkit knowledge add https://example.com/shipping --title "Shipping policy" # Attach a spec sheet to one product and share it with the sales space only flexkit knowledge add ./chair-spec.pdf --link product:product-chair --space sales ``` ## `knowledge update` Change a document's title, the spaces that can read it, or whether the agent can search it. ```bash flexkit knowledge update <sourceId> [--title <title>] [--space <code>... | --all-members] [--hide-from-agent | --show-to-agent] [--json] ``` ### Examples ```bash # Rename a document flexkit knowledge update 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --title "Returns policy 2026" # Only members of two spaces can read it flexkit knowledge update 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --space sales --space support # Keep it for people, but out of the agent's search flexkit knowledge update 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --hide-from-agent ``` ## `knowledge rm` Delete one or more documents with their passages and links. The command asks for confirmation; pass `--yes` in scripts. Alias: `remove`. ```bash flexkit knowledge rm <sourceId...> [--yes] [--json] ``` ### Examples ```bash # Delete a document flexkit knowledge rm 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f # Delete every document that failed to index flexkit knowledge ls --status failed --json | jq -r '.sources[].id' | xargs flexkit knowledge rm --yes ``` ## `knowledge reingest` Index a document again: an uploaded file from its stored copy, a web page from a fresh fetch. The current version stays searchable until the new one is ready. ```bash flexkit knowledge reingest <sourceId> [--wait] [--timeout <seconds>] [--json] ``` ### Examples ```bash # Re-fetch a web page that changed flexkit knowledge reingest 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f # Re-index and wait for the result flexkit knowledge reingest 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --wait ``` ## `knowledge download` Download the original file of an uploaded document, under its own file name. `dest` can be a file, a folder (existing, or ending in `/`) or `-` for stdout. Web pages have no stored file; open their address instead. ```bash flexkit knowledge download <sourceId> [dest] [--force] ``` ### Examples ```bash # Download into the current folder flexkit knowledge download 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f # Download into a backup folder flexkit knowledge download 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f ./backup/ # Stream the file to another tool flexkit knowledge download 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f - | pdftotext - - ``` ## `knowledge search` Search the documents you can read the way the agent does, and print the best passages with the document title and location (page, slide, heading). Results include documents hidden from the agent, since you can read them. ```bash flexkit knowledge search <query> [--limit <n>] [--source <sourceId>...] [--about <entity[:recordId]>] [--json] ``` ### Examples ```bash # Ask a question flexkit knowledge search "how long do customers have to return an item?" # Prefer the documents attached to one product flexkit knowledge search "assembly instructions" --about product:product-chair # Search two documents only flexkit knowledge search "late fees" --source 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f --source 0c9d8e7f-6a5b-4c3d-2e1f-0a9b8c7d6e5f # The text of the best passage flexkit knowledge search "warranty" --limit 1 --json | jq -r '.hits[0].text' ``` ## `knowledge link` and `knowledge unlink` Attach a document to a record, or to every record of an entity type when you leave out the record id; detach it the same way. `entity` is the entity name from your schema. ```bash flexkit knowledge link <sourceId> <entity> [recordId] [--json] flexkit knowledge unlink <sourceId> <entity> [recordId] [--json] ``` ### Examples ```bash # Attach a manual to one product flexkit knowledge link 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f product product-chair # Attach a policy to every order flexkit knowledge link 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f order # Detach it from orders again flexkit knowledge unlink 6b1f3c2e-4d5a-4e7b-8c9d-0a1b2c3d4e5f order ``` ## Options | Option | Subcommands | Description | | ---------------------------- | --------------------- | ------------------------------------------------------------------------------------ | | `--search <text>`, `-s` | `ls` | Only documents whose title or content matches. | | `--status <status>` | `ls` | `processing`, `ready` or `failed`. | | `--limit <n>`, `-n` | `ls`, `search` | Documents per page (1–100, default `25`), or passages to return (1–10, default `5`). | | `--offset <n>` | `ls` | Documents to skip. Default `0`. | | `--title <title>` | `add`, `update` | Document title; with `add`, only for a single input. | | `--space <code>` | `add`, `update` | Space code that may read the document. Repeatable. Default: every project member. | | `--all-members` | `update` | Let every project member read the document. | | `--hide-from-agent` | `add`, `update` | Keep documents out of the agent's search. | | `--show-to-agent` | `update` | Let the agent search the document again. | | `--link <entity[:id]>`, `-l` | `add` | Attach every added document to a record or entity type. Repeatable. | | `--concurrency <n>`, `-c` | `add` | Uploads in parallel, 1–10. Default `3`. | | `--wait` | `add`, `reingest` | Wait until indexing finishes. | | `--timeout <seconds>` | `add`, `reingest` | How long `--wait` waits. Default `600`. | | `--source <sourceId>` | `search` | Only search these documents. Repeatable, up to 10. | | `--about <entity[:id]>` | `search` | Prefer the documents attached to a record or entity type. | | `--force`, `-f` | `download` | Overwrite an existing file. | | `--yes`, `-y` | `rm` | Skip the confirmation prompt. | | `--json` | all except `download` | Print JSON on stdout. | | `--project <ID>`, `-p` | all | Project to use. Default: the [linked](/docs/cli/link) project. | See also the [global options](/docs/cli/global-options). ## Permissions and limits - **Reading** (`ls`, `inspect`, `search`, `download`, and following indexing with `--wait`) is open to every project member and every project API token. - **Writing** (`add`, `update`, `rm`, `reingest`, `link`, `unlink`) needs the **Owner** or **Developer** role, for a person and for a project API token alike. - You only see documents shared with every member or with one of your spaces, and you can only change documents whose spaces you all belong to. A project API token sees the spaces it was granted when it was created. - With a project API token, uploads count against the daily upload limit of the member who created the token. - Files are limited to 20 MB. Your plan sets the number of documents per project and the uploads per member per day; `add` reports the limit when you reach it. ## Common workflows ```bash # Load a folder of policies, attach them to every order, and wait until searchable flexkit knowledge add ./policies --link order --wait # Check that the agent will find the answer flexkit knowledge search "can a customer cancel after shipping?" # Re-index every web page, for example from a nightly job flexkit knowledge ls --limit 100 --json \ | jq -r '.sources[] | select(.kind == "url") | .id' \ | xargs -n1 flexkit knowledge reingest ``` The agent also reads knowledge through the [MCP server](/docs/integrations/mcp) tools `search_knowledge` and `read_source`. --- [View full sitemap](/docs/sitemap.md)