AACSearch CLICopy Anchor Link

aacsearch-cli runs on your machine and talks only to the AACSearch HTTP API through the generated TypeScript SDK. It does not start a local search engine.

Indexing is modeled after incremental pipelines (same idea as CocoIndex): target = transform(source). Each source file is a processing unit with a stable id; unchanged files are skipped when both the content hash and transform fingerprint match; deleted files remove their documents from the index.

InstallCopy Anchor Link

pnpm --filter @repo/sdk build
pnpm --filter aacsearch-cli build   # also: pnpm --filter aacsearch-cli test
node integrations/aacsearch-cli/dist/cli.js --help

Optional PDF: prefer Docling (pip install docling); fallback pnpm add pdf-parse --filter aacsearch-cli. Docling OCR is off by default.
Optional semantic code chunks: web-tree-sitter (optional dep) + vendored WASM grammars (JS/TS/Python/Go/Rust/Java/JSON/Bash); other languages use size/overlap fallback.

Local stack (:3000) walkthrough: integrations/aacsearch-cli/examples/README.md.

LoginCopy Anchor Link

aacsearch init --base-url https://search.example.com --index documentation --pipeline
aacsearch login --api-key aac_live_…

init --pipeline scaffolds aacsearch.yaml in the current directory. Or set AAC_API_KEY and AAC_BASE_URL.

Pipeline configCopy Anchor Link

Put aacsearch.yaml or .aacsearch/pipeline.json in the source root (or pass --config). See integrations/aacsearch-cli/examples/aacsearch.yaml.

version: 1
index: documentation
sources:
  - path: .
    include: ["**/*.md", "**/*.txt", "**/*.csv", "**/*.html", "**/*.pdf"]
honorGitIgnore: true
maxFileSize: 10485760
concurrency: 4
localChunk:
  enabled: false
parser: auto # auto | docling | pdf-parse
reembed: auto # auto when index has vectors | true | false
transforms:
  key: v1

Markdown YAML frontmatter (title, tags) is mapped into document metadata. .gitignore is honored by default (--no-gitignore to disable). Symlinks and oversize files are skipped.

Incremental update (catch-up)Copy Anchor Link

aacsearch update ./docs --index documentation
aacsearch update ./docs --include "**/*.md,**/*.txt,**/*.csv" --dry-run --explain
aacsearch update ./docs --preview        # alias of --dry-run
aacsearch update ./docs --full
aacsearch update ./docs --full-reprocess # alias of --full
aacsearch update ./docs --concurrency 8 --max-file-size 5242880
aacsearch update ./docs --chunk          # API-side chunking
aacsearch update ./docs --local-chunk    # local split → {pathHash}#c{n} (code → tree-sitter)
aacsearch update ./docs --parser auto    # Docling when available, else pdf-parse
aacsearch update ./docs --reembed        # force API reembed after writes
aacsearch update ./docs --no-reembed
aacsearch update ./docs --urls urls.txt  # public http(s) URL list (HTML title + strip)
aacsearch update ./docs --transform-key v2
aacsearch --json update ./docs --dry-run # scripting
aacsearch -q update ./docs               # quiet (CocoIndex-style)

A successful run prints processed / wrote (inserted, updated) / skipped / deleted counts (plus chunks wrote/reused when --local-chunk skips identical #cN bodies). After writes, the CLI may call AACSearch API reembed (?all=true) and print reembed started job_id=… — embeddings are computed by the API, not a local model. Crash-safe resume: an in-progress checkpoint under ~/.aacsearch/state/ records completed paths; the next update continues without redoing finished upserts. Bumping sync logic version clears transform fingerprints so files reprocess.

Lineage and sync statusCopy Anchor Link

aacsearch lineage ./docs
aacsearch sync-status ./docs   # parsers, tree-sitter grammars, reembed mode
# alias:
aacsearch doctors ./docs

Live push (filesystem CDC-style)Copy Anchor Link

aacsearch watch ./docs --interval 400 --local-chunk
aacsearch live ./docs --interval 200
# external bridge (filesystem paths only):
echo '{"op":"upsert","path":"a.md"}' | aacsearch live ./docs --stdin-events

On add/change the CLI upserts that file immediately; on unlink it deletes the target documents from local sync state. Bursts are coalesced; a failed path upsert is retried once without killing the watcher.

Connector bridge (DB / Kafka → CLI)Copy Anchor Link

Database / Kafka CDC remains AACSearch connectors in the console / API. Use --stdin-events when an external consumer can emit relative paths as NDJSON:

my-cdc-tail | aacsearch live ./docs --stdin-events
# {"op":"upsert"|"delete","path":"rel/path.md"}

See integrations/aacsearch-cli/examples/stdin-events.ndjson.

On Windows, recursive fs.watch can miss events; the CLI polls via --interval when recursive watch fails.

Search and index opsCopy Anchor Link

aacsearch search "pricing" --index documentation --per-page 10
aacsearch suggest "pri" --index documentation
aacsearch multi-search "pricing" --indexes documentation,help
aacsearch indexes
aacsearch create-index --name "Docs" --slug documentation
aacsearch delete <external_id> --index documentation
aacsearch reembed --index documentation

Scopes: document writes need documents:write; search/suggest need search:read; create-index needs org-wide indexes:write. Missing-scope errors include a Hint.

Out of scopeCopy Anchor Link

Kafka/DB CDC (use AACSearch connectors), local embedding models, CocoIndex Python DSL, and a lineage web UI are not part of this CLI.

See also the TypeScript SDK.