--- title: "CLI Reference" description: "Command reference for xio-lucent, the XI Lucent terminal tool for scripting ingestion, querying, and collection management." published: 2026-05-14T12:11:12.970589+00:00 updated: 2026-05-14T12:11:12.970589+00:00 tags: ["api", "cli", "lucent", "reference"] url: https://xiobjects.com/docs/xio/lucent/api/cli source: XI Objects --- # CLI Reference `xio-lucent` is the XI Lucent terminal tool. Install it as a .NET global tool, point it at a running Lucent API server, and use it to script ingestion, run queries, and manage collections from the command line. ## Install ```bash dotnet tool install -g Xio.Lucent.Cli ``` ## Connect to a server Store credentials for a server. Credentials are saved locally and reused for subsequent commands. ```bash xio-lucent login --url https://lucent.example.com/ --api-key sk_live_… ``` --- ## Commands ### login ```bash xio-lucent login --url --api-key ``` Saves the server URL and API key for subsequent commands. Use `--url` to switch between environments. --- ### provision Downloads and verifies the ONNX model and sqlite-vec extension on the remote server. Call this once after deploying a fresh server. ```bash xio-lucent provision ``` --- ### warmup Warms up the embedder on the remote server. Call after a cold start if the first query latency matters. ```bash xio-lucent warmup ``` --- ### docs add Ingests a document from a file or stdin. ```bash # From a file xio-lucent docs add --file spec.pdf # From stdin cat notes.md | xio-lucent docs add --file-name notes.md # With an explicit document ID xio-lucent docs add --file report.docx --document-id q1-report # With metadata xio-lucent docs add --file policy.pdf \ --meta category=legal --meta status=approved # As XION-signed content xio-lucent docs add --file signed.xion.md --xion ``` **Options:** | Option | Description | |--------|-------------| | `--file ` | File to ingest | | `--file-name ` | File name (used with stdin for content type detection) | | `--document-id ` | Explicit document ID | | `--content-type ` | Override content type detection | | `--meta ` | Add metadata; repeat for multiple pairs | | `--xion` | Trigger XION verification before ingestion | --- ### docs list Lists documents in a collection. ```bash xio-lucent docs list ``` Output includes document ID, content type, chunk count, model ID, and ingest timestamp. --- ### docs delete Removes a document and all its chunks. ```bash xio-lucent docs delete

``` --- ### docs source Retrieves the preserved XION bytes for a document and writes them to a file. ```bash xio-lucent docs source

-o restored.xion.md ``` Returns an error if the document wasn't ingested as XION content. --- ### query Runs a hybrid search and prints ranked results. ```bash # Basic query xio-lucent query "what is the cancellation policy" # Limit results xio-lucent query "rate limiting" --top-k 5 # Set score threshold xio-lucent query "authentication flow" --threshold 0.4 # Output as JSON xio-lucent query "data retention" --json ``` **Options:** | Option | Description | |--------|-------------| | `--top-k ` | Maximum results (default 10) | | `--threshold ` | Minimum score cutoff (0–1) | | `--json` | Output full result as JSON | Default output shows score, source (`vector`/`text`/`hybrid`), chunk content excerpt, and provenance (file, page number, heading). --- ### export Streams a collection backup to a file. ```bash xio-lucent export -o backup.lucent ``` --- ### import Restores a collection from a backup file. ```bash xio-lucent import --file backup.lucent ``` --- ## Scripting examples Ingest all PDFs in a directory: ```bash for f in docs/*.pdf; do xio-lucent docs add specs --file "$f" --meta source=docs-folder done ``` Export a collection and import it into another environment: ```bash xio-lucent export my-collection -o backup.lucent xio-lucent login --url https://staging.lucent.example.com/ --api-key sk_staging_… xio-lucent import my-collection --file backup.lucent ``` Verify the count after import: ```bash xio-lucent docs list my-collection | wc -l ```