Skip to main content

OneSearch CLI

Command-line interface for OneSearch - Self-hosted, privacy-focused search for your homelab.

Installation

The CLI is a standalone client for a running OneSearch server. It does not include the backend, indexer, or search data. Tagged OneSearch releases publish the Docker image and the onesearch-cli package together on the same shared version.

pipx install onesearch-cli
onesearch config set backend_url http://localhost:8000
onesearch login

From Source (Development)

cd cli
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/Mac
source .venv/bin/activate

pip install -e .

Verify Installation

onesearch --version
onesearch --help

Quick Start

# Check system health
onesearch health

# List configured sources
onesearch source list

# Add a source (ID is auto-generated from name as slug, e.g., "documents")
onesearch source add "Documents" /data/docs --include "**/*.pdf,**/*.md"

# Trigger indexing (use source ID from 'source list')
onesearch source reindex documents

# Search
onesearch search "kubernetes deployment"

# Check indexing status
onesearch status

Note: Source IDs are slugified from the name (e.g., "My Documents" → "my-documents").

Commands

Source Management

# List all sources
onesearch source list

# Add a new source
onesearch source add <name> <path> [--include PATTERNS] [--exclude PATTERNS]

# Show source details
onesearch source show <source_id>

# Reindex a source
onesearch source reindex <source_id>

# Delete a source
onesearch source delete <source_id> [--yes]
# Basic search
onesearch search "query"

# With filters (use source ID from 'source list')
onesearch search "python" --source documents --type pdf --limit 10

# JSON output for scripting
onesearch search "error" --json | jq '.results[].path'

# Pagination
onesearch search "docker" --offset 20 --limit 10

Status & Health

# Overall status
onesearch status

# Specific source status
onesearch status <source_id>

# System health check
onesearch health

# JSON output for monitoring
onesearch health --json

Configuration

Environment Variables

  • ONESEARCH_URL - Backend API URL (default: http://localhost:8000)
  • ONESEARCH_TOKEN - Bearer token for non-interactive auth
# Use a custom backend URL
export ONESEARCH_URL=http://onesearch.local:8000
onesearch search "test"

# Non-interactive auth for scripts
export ONESEARCH_TOKEN=xxxxx
onesearch search "test" --json

# Or pass the URL directly
onesearch --url http://onesearch.local:8000 search "test"

Global Options

  • --url URL - Override backend API URL
  • -v, --verbose - Enable verbose output
  • -q, --quiet - Suppress non-essential output (headers, hints, decorations)
  • -h, --help - Show help message
  • --version - Show version

Output Formats

Most commands support --json for machine-readable output:

# JSON for scripting
onesearch health --json
onesearch status --json
onesearch search "test" --json

Examples

Add and Index a Source

# Add a documents source (creates ID "my-documents")
onesearch source add "My Documents" /mnt/nas/documents \
  --include "**/*.pdf,**/*.md,**/*.txt" \
  --exclude "**/archive/**"

# Start indexing (use the source ID)
onesearch source reindex my-documents

# Monitor progress
onesearch status my-documents

Docker users: If the path only exists inside the container, use --no-validate to skip local path validation:

onesearch source add "NAS Docs" /data/nas --no-validate

Search with Filters

# Search PDFs only
onesearch search "quarterly report" --type pdf

# Search specific source (use source ID)
onesearch search "meeting notes" --source my-documents

# Get more results
onesearch search "python" --limit 50

Health Monitoring

# Quick health check (returns non-zero on failure)
onesearch health || echo "OneSearch is down!"

# JSON for monitoring systems
onesearch health --json | jq '.status'

Development

# Install CLI in development mode
pip install -e .

# Run tests (install pytest first)
pip install pytest
pytest

Metadata

Release files for onesearch-cli 1.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onesearch-cli 1.8.0
File Size Uploaded Provenance Actions
onesearch_cli-1.8.0.tar.gz 18.0 kB Without provenance Details for onesearch_cli-1.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onesearch-cli 1.8.0
File Interpreter ABI Platform Actions
onesearch_cli-1.8.0-py3-none-any.whl Python 3 none any Details for onesearch_cli-1.8.0-py3-none-any.whl

Total release size: 38.4 kB

Release files / onesearch_cli-1.8.0.tar.gz

Download URL onesearch_cli-1.8.0.tar.gz
Size 18.0 kB
Tags Source
SHA-256 checksum
How to use checksums
482b30e58af394d6eab387add44ccc033382077655bc69566f9022de42063f5d
BLAKE2b-256 checksum
How to use checksums
cc0745521aab3ab95e55a295f8336c7f3233550eb2c0da5ff882214d9d2efe7c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Release files / onesearch_cli-1.8.0-py3-none-any.whl

Download URL onesearch_cli-1.8.0-py3-none-any.whl
Size 20.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
44c3321682f36ac5a7ab88a916b73a80d35174faa8907c5154b17db489c7226c
BLAKE2b-256 checksum
How to use checksums
da485d21cdf9094224303c08c5c6fbfaac198fe2b9f0940732adcee840a4b8aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.15

Security for onesearch-cli 1.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page