Unique CLI -- Knowledge Base Search & Document Read

search vs read — which command to use

Situation	Command
You have a query or topic and want to find relevant chunks across documents	unique-cli search "<query>"
You already have a cont_* ID and want the full indexed text of that document	unique-cli read <cont_id>

What "full indexed text" means: the platform has already ingested the document — OCR for scanned pages, extracted text from PDFs and Office files, and image descriptions from figures/charts. read returns that pre-processed text directly; you do not need to download the file or run OCR yourself. If read returns no chunks after ingestion should be complete, download the file with unique-cli download and inspect it directly — ingestion occasionally fails and the raw file must be checked.

Use read after a ls or search surfaces a content ID and you need to go deeper into that specific document — it retrieves every chunk directly from the database with no query needed. Use search for discovery.

---

Search the Unique knowledge base using combined vector + full-text search via the unique-cli search command. Every invocation wraps each result in a <sourceN>...</sourceN> block and records a per-turn citation manifest at .unique/kb-search-refs.jsonl, so any fact you cite as [sourceN] is rendered with a footnote and a clickable reference chip in the chat UI.

Limitation: Excel (.xlsx/.xls), CSV (.csv), and image files are not full-text indexed. They will not appear in search results. To find these files, use the unique-cli-file-management skill and browse folders with unique-cli ls to locate them by name.

Basic Search

# Search across the entire knowledge base
unique-cli search "quarterly revenue analysis"

# Limit results
unique-cli search "budget forecast" --limit 50

Scoped Search

Restrict search to a specific folder:

# By absolute path
unique-cli search "growth" --folder /Reports/Q1

# By folder name (relative to current dir in interactive mode)
unique-cli search "growth" -f Q1

# By scope ID
unique-cli search "growth" -f scope_abc123

When no --folder is given:

• If the task defines a scope (a per-message scope filter): that scope is the search boundary, regardless of the current directory. cd/cwd does not narrow further — only an explicit --folder ANDs an additional constraint. You do not need --folder here — just run unique-cli search "<query>". Passing a folder path that isn't navigable to your user errors with Folder ... not found; only narrow within the scope via a scope_ id.
• Otherwise, in interactive mode: searches within the current directory
• Otherwise, at root /: searches the entire knowledge base

Note: When a task scope is active, cd itself is not gated — you can cd into a folder outside the task scope, but ls, read, cite, download, etc. will then deny from there with a hint naming the in-scope folders/documents. A denial after cding into a sibling folder is expected: move back to an in-scope folder (or use search, which already searches the whole task scope regardless of cwd).

Metadata Filtering

Filter by metadata fields using --metadata key=value (repeatable, AND logic):

# Single filter
unique-cli search "compliance" --metadata department=Legal

# Multiple filters (AND)
unique-cli search "audit" -m department=Legal -m year=2025

# Combined with folder scope
unique-cli search "regulatory" -f /Legal -m year=2025 -l 50

Command Reference

unique-cli search <query> [--folder <path|scope_id>] [--metadata <key=value>]... [--limit <N>]

Option	Short	Default	Description
--folder	-f	Task scope, else current dir	Folder path, name, or scope ID
--metadata	-m	None	Key=value filter (repeatable)
--limit	-l	200	Max results

Output Format

Each result is rendered as a <sourceN>...</sourceN> block. N is 1-based, unique within the current turn, and continues across multiple unique-cli search calls in the same turn — the first call in a turn starts at <source1>, a follow-up call that returns three more results emits <source4>, <source5>, <source6>, and so on.

Found 2 result(s):

<source1>
<|document|>annual-report.pdf</|document|>
<|page|>12-13</|page|>
<|info|>cont_abc123</|info|>
...the quarterly revenue analysis shows a 15% increase...
</source1>

<source2>
<|document|>Q1/financials.xlsx</|document|>
<|page|>1</|page|>
<|info|>cont_def456</|info|>
...revenue breakdown by quarter indicates strong growth...
</source2>

Each block carries the document title, page range (when known), content ID, and a text snippet. The full chunk metadata (chunkId, url, startPage, endPage, ...) is captured in the per-turn manifest and not duplicated on screen.

Citation Rules

Cite a fact from unique-cli search results with [sourceN], where N matches the number on the <sourceN> block you read it from. The Unique platform's Swappable Intelligence runner converts each [sourceN] marker in your final answer into a <sup>N</sup> footnote and a clickable reference chip; without unique-cli search, KB facts in your answer appear as plain text only, with no footnote and no chip — so this is the only way to make KB citations render correctly on the platform.

The company's quarterly revenue rose 15% year over year [source1],
driven by strong growth in the EMEA segment [source2].

Rules (enforced by the platform's reference post-processor):

1. [sourceN] is for KB results only. Web results from unique-cli web-search use [websourceN] instead — never mix the two namespaces.
2. Only cite numbers you saw in the current turn's unique-cli search output. Numbers from previous turns are stale and will be silently dropped.
3. Write source in singular form with the number in digits: [source1], [source2] — not [Source 1] or [source one].
4. Prefer citing each fact with a single, most-relevant source.
5. Do not invent source numbers for remembered or inferred facts.

Scripting with Search

# Search and count results
unique-cli search "policy update" -l 500 | head -1

# Search specific folder with metadata
unique-cli search "Q4 earnings" \
  --folder /Finance/Reports \
  --metadata status=published \
  --metadata year=2025 \
  --limit 100

Reading a Document by ID (read)

When you already know a cont_* ID, use read to retrieve every indexed chunk in one call:

unique-cli read cont_abc123

Output:

Content: annual-report.pdf (cont_abc123) — 42 chunk(s)

[p.1] The company was founded in 1998 with a focus on...

[p.2-3] Revenue grew 15% year over year, driven by...

[p.4] Key risks include supply chain disruptions...

Each paragraph is one ingested chunk (OCR, extracted text, image descriptions) prefixed with its page range when available. No further file parsing or OCR is required on your side.

When chunks are empty: if the document was just uploaded and ingestion hasn't finished, read returns a message saying so — retry after a short wait. If chunks stay empty after a reasonable wait, download the file (unique-cli download <cont_id>) and inspect it yourself; some files are not ingested correctly and must be read directly.

read does not produce [sourceN] citations — but you do not need to re-search to cite a document you have already read. When you have the cont_* ID, declare citations directly with unique-cli cite <cont_id> --pages <N> (documented in the unique-cli-file-management skill). cite registers [filesourceN] markers that render as footnotes and clickable chips on the platform, working straight from the ingested index — no re-search and no file download required, and the page numbers it expects are the same [p.N] physical positions read already prints. Re-run unique-cli search only when you actually need relevance-ranked [sourceN] chunks across documents you have not yet identified — not merely to cite something you just read.

Prerequisites

Requires these environment variables:

UNIQUE_USER_ID    # User ID (required)
UNIQUE_COMPANY_ID # Company ID (required)
UNIQUE_API_KEY    # API key — optional on localhost / secured cluster
UNIQUE_APP_ID     # App ID — optional on localhost / secured cluster

Install: pip install unique-sdk