---
name: takibi-use
description: Use the Takibi knowledge base and task board through the takibi CLI (ask, search, tasks, docs). Use whenever the user asks about Takibi content, evidence-backed answers from their docs, or crew task boards.
---

# takibi-use: Takibi via the CLI

Always use the CLI. Never hand-roll curl/fetch against `/v1/*` — the CLI
already bakes in the auth shape, the `q` param, project resolution, and
error hints.

## Setup (once)

- CLI: `node tools/takibi/takibi.mjs …` from the takibi-base checkout
  (the founder may alias it as `takibi`; use the alias when it exists).
- Key: the founder saves one `<publicId>.<secret>` line to `~/.takibi/key`
  (`chmod 600`). The key is never printed, never pasted in chat, never
  committed. If a command says the key is missing, stop and ask.
- Base URL defaults to `http://localhost:3849` (local boot). Override with
  `$TAKIBI_BASE_URL` or one URL line in `~/.takibi/config`.
- Projects: `takibi projects` lists saved names. `--project` takes a name
  or a UUID; single-grant keys may omit it. New name? Ask the founder for
  the UUID once, then `takibi projects --add <name> <uuid>`.
- First probe: `takibi version` (needs no key; shows build + `jev` status).

## Commands

- `takibi ask -q "…"` — answer from the evidence. Output is verbatim spans
  with citations plus a support line. `--project`, `--folder <uuid>`,
  `-k 1-12`, `--json`.
- `takibi search -q "…"` — ranked chunks (snippets + metadata, not full
  text). Same flags, `-k 1-20`.
- `takibi tasks list | get <id> | claim <id> | status <id> <todo|in_progress|review|done>`
  and `takibi tasks artifact add <taskId> <url> [--note …]`.
- `takibi doc list | get <id> | text <id>` — metadata, then converted text.
  `doc download` is founder-only; the CLI says so — use `doc text`.
- `--json` anywhere prints raw server JSON. `--verbose` logs requests
  (never the key). Exit 0 = ok, 1 = transport/API error, 2 = usage error.

## Reading answers

- Spans are verbatim with citations (`doc <uuid>`, `chunk <uuid>`) and a
  versioned support score. Support is not confidence — report the number,
  never upgrade it into certainty.
- Honor `answerability` (`answerable|partial|unanswerable|unknown`) and
  `conflict`. On `conflict: yes`, surface both sides; never smooth it over.
- Jev-down is not app-down: `/ask` still answers with degraded fields
  (`answerability: unknown`, `conflict: false`) and search is unaffected.

## Abstains (exit 0, not an error)

`abstained: true` (`No answer in the evidence.`) means: broaden `q`, fall
back to `search`, try `doc text` on the hits — then either answer from
evidence or say the evidence is not there. Never fill gaps with generated
prose presented as sourced.

## Mutation policy

- Reads are free: ask, search, tasks list/get, doc list/get/text.
- Task claim/status/artifact writes only with founder approval already
  given in conversation. Claim-first: a plain key must claim a card before
  moving or touching it; only orchestrators/founders accept (`review→done`),
  assign others, or archive.
- Founder-only routes (upload, delete, retry, download originals, PATCH
  docs/projects) are never the agent's to call — ask the founder.

## Failure table

- 401: key wrong/missing/revoked/disabled — or a founder-only route
  (the CLI names it). 403: outside the grant or orchestrator-only.
  404: bad id (the server hides grant gaps as 404 too).
- 409 on claim: someone already holds the card — the message names them.
- 429: minute throttle (slow down) or daily budget spent (resets tomorrow).
- Cannot-reach errors: the API is not booted; `takibi version` probes it.