Skip to content

Unique-AG/ai / unique_sdk/unique_sdk/cli/skills/unique-cli-search

unique-cli-search

Verified

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).

FileKindSize
SKILL.mdskill md11.1 KB
---
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`
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall