Skip to main content
Manage indexes, documents, and queries from the terminal. 
pip install moss-cli
The installed binary is moss.

​
Authentication

Credentials are resolved in this order:
  1. CLI flags: --project-id and --project-key
  2. Environment variables: MOSS_PROJECT_ID and MOSS_PROJECT_KEY
  3. 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
FlagDescription
--file / -fPath to JSON/CSV document file, or - for stdin
--model / -mEmbedding model (default: moss-minilm)
--wait / -wBlock until the build job finishes
--poll-intervalSeconds between status checks (default: 2.0)
--confirm / -ySkip 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
FlagDescription
--file / -fPath to JSON/CSV document file, or - for stdin
--upsert / -uUpdate documents that already exist
--ids / -iComma-separated document IDs
--wait / -wBlock 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'
FlagDescription
--top-k / -kNumber of results (default: 10)
--alpha / -aSemantic weight; 0.0 is pure keyword, 1.0 is pure semantic (default: 0.8)
--cloud / -cQuery via cloud API instead of downloading the index
--filterMetadata filter as JSON string. Local mode only.
--interactiveREPL 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

FlagShortDescription
--project-id-pProject ID; overrides env and config
--project-keyProject key; overrides env and config
--profileCredential profile name; overrides MOSS_PROFILE
--jsonMachine-readable JSON output
--verbose-vEnable debug logging

​
Models

ModelDescription
moss-minilmLightweight, optimized for speed (default)
moss-mediumlmHigher accuracy with reasonable performance
customUsed automatically when documents include pre-computed embeddings