Documentation Index
Fetch the complete documentation index at: https://docs.moss.dev/llms.txt
Use this file to discover all available pages before exploring further.
Manage indexes, documents, and queries from the terminal.
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
/set alpha 0.5
/set top-k 10
/exit
--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
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"}}
]
{"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 |
