Connect an agent
Install the CLI, save a scoped key, and give your agent a way to retrieve source passages.
Install the CLI and skill
You need Node.js 20 or newer and a key from a Profile with access to at least one indexed document. If you do not have those yet, follow Your first retrieval.
Run the latest CLI release with npx, or install it globally:
npx takibibase@latest --help
npm i -g takibibase # then: takibi --helpPrefer a single file? Download takibi.mjs and save it as tools/takibi/takibi.mjs in your working directory. The CLI is a single file with no package dependencies. Run it with Node, or alias it:
alias takibi='node /absolute/path/to/tools/takibi/takibi.mjs'
takibi --helpDownload the Takibi agent skill into your tool's skills directory, or install it from the CLI with takibi skill --install (repeat --dir <skills-root> per custom box; --force refreshes an older copy). You can also give its instructions to your agent directly. The skill assumes a takibi command on PATH or npx takibibase@latest. Tools may run in different working directories, so check the path from the agent's environment too.
The CLI checks for updates once a day and prints a one-line notice when a newer release exists. The notice goes to stderr, so scripts and --json output are unaffected.
Save the key
The CLI talks to Takibi's servers by default. There is no endpoint to configure. Save the key where the agent runs:
mkdir -p ~/.takibi
touch ~/.takibi/key
chmod 600 ~/.takibi/keyUse an editor to save the complete publicId.secret key as the only line in ~/.takibi/key. Do not paste the secret into shell history or chat. The account running the agent must be able to read that file.
Run takibi version to check the connection. This probe does not need a key, so a successful version response does not prove the key or grants are valid. Test those with a permitted search or question next.
Choose the collection
If the Profile has one collection, the CLI selects it automatically. Otherwise run takibi projects to see what the key can reach, then pass --project <name-or-uuid>. Profiles with only tag grants list no collections. Pass a collection ID from the same workspace explicitly.
Names resolve through the API (a name shared by two collections must use the UUID); takibi projects --add <name> <uuid> keeps local aliases for offline use. If a collection is missing from the list, check the Profile's Access settings — the list shows granted scope, nothing more.
Ask, search and read the evidence
takibi ask -q "What is our refund policy?" --json
takibi search -q "refund eligibility" --json
takibi doc text <document-uuid>Ask returns exact source passages and citations. Search returns ranked snippets so you can find relevant material. Doc text reads the permitted converted text for a document.
| Field | Meaning |
|---|---|
spans and citations | The retrieved passages and their document/chunk references. Check the source context before drawing conclusions. |
support and supportVersion | How strongly the passages back the question, scored by the version named in supportVersion. It is not a probability that a claim is true. |
answerability | Can be answerable, partial, unanswerable or unknown. Partial evidence may cover only part of the question. |
conflict | Flags detected contradictions. A false flag does not prove that no contradiction exists. |
abstained | When true, no passages were returned. This is a successful response with no evidence, not a transport failure. |
If no passages come back, check the Profile's access and document status, try a narrower question, or search for a specific phrase. Do not treat missing evidence as a negative answer. If the AI ranking step is unavailable, results fall back to plain keyword matching. Search keeps working either way.
Let the agent do useful work
Have the agent cite the returned documents and distinguish source evidence from its own interpretation. Give it explicit approval before task-changing actions, then follow the task workflow. Agents file documents with takibi doc upload <file> --project <name-or-uuid> once you enable Uploads on their Profile and approve the filing.
For failed requests, see error diagnosis. For a direct integration, use the API reference and its static OpenAPI download.