Moss - Real-time Semantic Search for Conversational AI

Manage indexes, documents, and queries from the terminal.

pip install moss-cli

The installed binary is moss.

Authentication

Credentials are resolved in this order:

CLI flags: --project-id and --project-key
Environment variables: MOSS_PROJECT_ID and MOSS_PROJECT_KEY
Config profile: selected by --profile, MOSS_PROFILE, or the active profile in ~/.moss/config.json

# Interactive setup (recommended)
moss init
moss init --profile staging

# Environment variables
export MOSS_PROJECT_ID="your-project-id"
export MOSS_PROJECT_KEY="your-project-key"

# Inline flags
moss index list --project-id "..." --project-key "..."

# Profile-based
moss index list --profile staging
moss profile list

Quick start

# 1. Save credentials
moss init

# 2. List indexes
moss index list

# 3. Create an index from a JSON file
moss index create my-index -f docs.json --wait

# 4. Search it
moss query my-index "what is machine learning"

# 5. Search via cloud API (skips local download)
moss query my-index "neural networks" --cloud

Index management

# Create
moss index create my-index -f documents.json --model moss-minilm
moss index create my-index -f documents.json --wait

# List
moss index list

# Inspect
moss index get my-index

# Delete
moss index delete my-index
moss index delete my-index --confirm     # skip prompt

Flag	Description
`--file` / `-f`	Path to JSON/CSV document file, or `-` for stdin
`--model` / `-m`	Embedding model (default: `moss-minilm`)
`--wait` / `-w`	Block until the build job finishes
`--poll-interval`	Seconds between status checks (default: `2.0`)
`--confirm` / `-y`	Skip confirmation prompt on delete

Document management

# Add documents
moss doc add my-index -f new-docs.json
moss doc add my-index -f docs.json --upsert --wait

# Retrieve documents
moss doc get my-index
moss doc get my-index --ids doc1,doc2,doc3

# Delete documents
moss doc delete my-index --ids doc1,doc2

Flag	Description
`--file` / `-f`	Path to JSON/CSV document file, or `-` for stdin
`--upsert` / `-u`	Update documents that already exist
`--ids` / `-i`	Comma-separated document IDs
`--wait` / `-w`	Block until the job finishes

Query

Queries download the index locally by default and run on-device. Add --cloud to skip the download and hit the cloud query API.

# Local query (downloads the index on first use)
moss query my-index "what is deep learning"

# Tune results
moss query my-index "neural networks" --top-k 20 --alpha 0.3

# Cloud query
moss query my-index "transformers" --cloud

# Metadata filter (local only)
moss query my-index "shoes" --filter '{"field": "category", "condition": {"$eq": "footwear"}}'

# Pipe from stdin
echo "what is AI" | moss query my-index

# JSON output for scripting
moss query my-index "query" --json | jq '.docs[0].text'

Flag	Description
`--top-k` / `-k`	Number of results (default: `10`)
`--alpha` / `-a`	Semantic weight; `0.0` is pure keyword, `1.0` is pure semantic (default: `0.8`)
`--cloud` / `-c`	Query via cloud API instead of downloading the index
`--filter`	Metadata filter as JSON string. Local mode only.
`--interactive`	REPL session against a single loaded index

Interactive mode

moss query my-index --interactive
moss query my-index --interactive --top-k 20 --alpha 0.4

In the prompt:

/set alpha 0.5
/set top-k 10
/exit

Interactive mode is local-only (does not support --cloud) and is not compatible with --json. With redirected or piped stdin, the piped query is run once and the session exits.

Job tracking

# Check status
moss job status <job-id>

# Wait with live progress
moss job status <job-id> --wait

Profiles

moss profile list
moss profile delete staging --force

Document file formats

JSON

[
  {"id": "doc1", "text": "Machine learning fundamentals", "metadata": {"topic": "ml"}},
  {"id": "doc2", "text": "Deep learning with neural networks"},
  {"id": "doc3", "text": "Natural language processing", "metadata": {"topic": "nlp"}}
]

A wrapper form is also accepted: {"documents": [...]}.

CSV

id,text,metadata
doc1,Machine learning fundamentals,"{""topic"": ""ml""}"
doc2,Deep learning with neural networks,
doc3,Natural language processing,"{""topic"": ""nlp""}"

stdin

cat docs.json | moss index create my-index -f -
cat docs.json | moss doc add my-index -f -

Global options

Flag	Short	Description
`--project-id`	`-p`	Project ID; overrides env and config
`--project-key`		Project key; overrides env and config
`--profile`		Credential profile name; overrides `MOSS_PROFILE`
`--json`		Machine-readable JSON output
`--verbose`	`-v`	Enable debug logging

Models

Model	Description
`moss-minilm`	Lightweight, optimized for speed (default)
`moss-mediumlm`	Higher accuracy with reasonable performance
`custom`	Used automatically when documents include pre-computed embeddings

Voice & Real-time

AI Frameworks

Developer Tools

Moss CLI

Authentication

Quick start

Index management

Document management

Query

Interactive mode

Job tracking

Profiles

Document file formats

JSON

CSV

stdin

Global options

Models

​Authentication

​Quick start

​Index management

​Document management

​Query

​Interactive mode

​Job tracking

​Profiles

​Document file formats

​JSON

​CSV

​stdin

​Global options

​Models

Authentication

Quick start

Index management

Document management

Query

Interactive mode

Job tracking

Profiles

Document file formats

JSON

CSV

stdin

Global options

Models