Unique-AG/ai / unique_sdk/unique_sdk/cli/skills/unique-cli-search
unique-cli-search
VerifiedSearch the Unique AI Platform knowledge base using the unique-cli search command, with automatic per-turn citation tracking so cited facts render as clickable reference chips and `<sup>N</sup>` footnotes on the Unique platform. Use whenever the user asks to find, search, or query documents or content on Unique, including filtering by folder or metadata. Also covers `unique-cli read <cont_id>` for reading the full indexed text of a document when its content ID is already known. NOTE: This search uses combined vector + full-text indexing. Excel (.xlsx/.xls), CSV (.csv), and image files are NOT full-text indexed, so they will not appear in search results. To locate these file types, use the unique-cli-file-management skill instead (browse folders with `unique-cli ls` to find them by name; `ls` shows 50 files at a time, so follow its "more:" line or use `--all` for larger folders).
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
SKILL.md
View on GitHub---
name: unique-cli-search
description: >-
Search the Unique AI Platform knowledge base using the unique-cli search
command, with automatic per-turn citation tracking so cited facts render
as clickable reference chips and `<sup>N</sup>` footnotes on the Unique
platform. Use whenever the user asks to find, search, or query documents
or content on Unique, including filtering by folder or metadata.
Also covers `unique-cli read <cont_id>` for reading the full indexed text
of a document when its content ID is already known.
NOTE: This search uses combined vector + full-text indexing. Excel
(.xlsx/.xls), CSV (.csv), and image files are NOT full-text indexed,
so they will not appear in search results. To locate these file types,
use the unique-cli-file-management skill instead (browse folders with
`unique-cli ls` to find them by name; `ls` shows 50 files at a time, so
follow its "more:" line or use `--all` for larger folders).
---
# 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 (`ls` shows 50 files at a time; follow its "more:" line or use `--all` for larger folders).
## Basic Search
```bash
# Search across the entire knowledge base
unique-cli search "quarterly revenue analysis"
# Limit results
unique-cli search "budget forecast" --limit 50
```
### Several searches: pass every query in ONE call
When you need more than one search (several topics, terms or
questions), give the first query as the argument and each further query
with `-q`. Do **not** run one `unique-cli search` call per query, and do
not start several in the background: the queries run concurrently inside
the one call and the answer comes back in one round. Quote every query
that has more than one word.
```bash
unique-cli search "revenue growth" -q "operating margin" -q "headcount plan"
```
- Up to 8 queries per call (4 run at the same time). More than 8 is an
error: split them across calls.
- `--folder`, `--metadata` and `--limit` apply to every query. `--limit` is
per query.
- The output starts with a summary line when a query failed or results
were left out, then has one block per query in the order you gave them,
each headed `=== query i/n ===` and `query: '<query>'`.
- A chunk found by several queries is shown once; later blocks list it as
`Also matched, shown in another block: [sourceN]`.
- The output stops at about 100,000 tokens. Results are taken best first
from every query in turn, so each query keeps its top results.
- `<sourceN>` numbers follow the query order and keep counting across calls
in the turn.
- A query that fails shows its own error and the other queries still
return. The command exits `1` only when every query failed.
- A single query behaves exactly as before.
- At most 100 `unique-cli search` calls run per minute, each with up to 8
queries. Beyond that the command refuses and says how long to wait.
## Scoped Search
Restrict search to a specific folder:
```bash
# 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 `cd`ing 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):
```bash
# 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> [-q <query>]... [--folder <path|scope_id>] [--metadata <key=value>]... [--limit <N>]
```
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--query` | `-q` | None | Another query in the same call (repeatable, up to 8 in total) |
| `--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 per query |
## 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
```bash
# 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:
```bash
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:
```bash
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`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |