Moss CLI

Command-line interface for Moss semantic search — manage indexes, documents, and queries directly from your terminal.

Moss CLI wraps the Moss Python SDK so you can build and query semantic search indexes without writing any code. Ideal for quick prototyping, scripting, CI/CD pipelines, and data workflows.

Features

• Full SDK coverage — every SDK operation available as a CLI command
• Semantic search — query indexes with configurable hybrid search (semantic + keyword)
• Index management — create, list, inspect, and delete indexes
• Document management — add, update, retrieve, and delete documents
• Local by default — downloads indexes and queries them on-device
• Flexible auth — CLI flags, environment variables, or config file
• Log in from the terminal — moss login, then create project keys with moss keys create
• Multiple output formats — rich tables for humans, --json for scripts
• Job tracking — poll background jobs with live progress display
• Pipe-friendly — stdin/stdout support for composing with other tools

Installation

pip install moss-cli

Quick Start

# 1. Save your credentials
moss init

# 2. List your 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"

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 file: ~/.moss/config.json (created by moss init)

# Option 1: Interactive setup (recommended)
moss init

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

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

Log in and create keys

moss login connects the CLI to your Moss account, so you can create project keys without opening the dashboard.

# Opens the browser. Check the code matches, then click Approve.
moss login

moss whoami
moss projects list

# Prints the key once, plus MOSS_PROJECT_ID / MOSS_PROJECT_KEY lines
moss keys create --project <project-id> --name "prod server"
moss keys list --project <project-id>
moss keys delete --project <project-id> <key-id>

# Revoke the token and remove it from ~/.moss/config.json
moss logout

The token is saved to ~/.moss/config.json. It lives until you run moss logout or revoke it in Settings > API Keys. It acts as you: only workspace owners, admins and a project's owner can create or delete its keys. --project defaults to the project saved by moss init.

Use moss login --no-browser on a machine without a browser (for example over SSH) and open the printed link anywhere.

Agents and CI

CI that only queries or uploads to one project needs a project key, not a login. Create one with moss keys create and store it as MOSS_PROJECT_ID / MOSS_PROJECT_KEY.

Agents that create or delete keys need a CLI token. Make a separate one for each agent, so logging in or out on your machine doesn't break it:

# Approve in the browser; the token is printed, not saved
moss login --print-token --name "deploy agent"

Store it as MOSS_TOKEN in your secret store, then:

export MOSS_TOKEN="mossc_..."
moss keys create --project <project-id> --json
# {"project_id": "...", "key_id": "...", "secret": "moss_..."}

The token acts as you, so it loses access to a workspace when you do. Revoke it in Settings > API Keys.

The token is resolved from --token, then MOSS_TOKEN, then the config file. The saved token is only sent to the dashboard that issued it, so with --api-url pointing elsewhere, log in there or pass --token. A --token or MOSS_TOKEN goes to production unless --api-url / MOSS_API_URL says otherwise.

Commands

Index Management

# Create an index with documents from a JSON file
moss index create my-index -f documents.json --model moss-minilm

# Create and wait for completion
moss index create my-index -f documents.json --wait

# List all indexes
moss index list

# Get index details
moss index get my-index

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

Document Management

# Add documents to an existing index
moss doc add my-index -f new-docs.json

# Add with upsert (update existing, insert new)
moss doc add my-index -f docs.json --upsert --wait

# Get all documents
moss doc get my-index

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

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

Query

# Search (downloads index and queries on-device by default)
moss query my-index "what is deep learning"

# Tune results: more results, keyword-heavy
moss query my-index "neural networks" --top-k 20 --alpha 0.3

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

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

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

Job Tracking

# Check job status
moss job status <job-id>

# Wait for job to finish (with live progress)
moss job status <job-id> --wait

Other

# Print version info
moss version

# Global JSON output
moss index list --json
moss doc get my-index --json

Document File Format

JSON (recommended)

[
  {"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"}}
]

Also supports a wrapper format: {"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/config)
--project-key		Project key (overrides env/config)
--token		CLI token from moss login (or MOSS_TOKEN)
--api-url		Dashboard URL, for staging or local testing (or MOSS_API_URL)
--json		Machine-readable JSON output
--verbose	-v	Enable debug logging

Available Models

Model	Description
moss-minilm	Lightweight, optimized for speed (default)
moss-mediumlm	Balanced accuracy and performance
custom	Used automatically when documents include embeddings

License

Copyright (c) 2026 InferEdge Inc. — PolyForm Shield License 1.0.0.

See LICENSE for full terms. For commercial licensing, contact contact@moss.dev.