Metadata-Version: 2.4
Name: moss-cli
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: moss>=1.0.0
Requires-Dist: typer>=0.26.8
Requires-Dist: rich>=15.0.0
Requires-Dist: pytest>=9.1.1 ; extra == 'dev'
Requires-Dist: black>=25.9.0,<26 ; extra == 'dev'
Requires-Dist: isort>=7.0.0,<8 ; extra == 'dev'
Requires-Dist: flake8>=7.3.0 ; extra == 'dev'
Requires-Dist: mypy>=2.1.0 ; extra == 'dev'
Requires-Dist: maturin>=1.9,<2 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
License-File: LICENSE-THIRD-PARTY.txt
Summary: Command-line interface for Moss semantic search
Keywords: search,semantic,cli,moss
Author-email: "InferEdge Inc." <contact@usemoss.dev>
License-Expression: LicenseRef-PolyForm-Shield-1.0.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# 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](https://docs.moss.dev/) 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

```bash
pip install moss-cli
```

## Quick Start

```bash
# 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`)

```bash
# 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 --project-id "..." --project-key "..." index list
```

With none of these, `moss index`, `moss doc` and `moss query` run in offline mode.

## Offline mode

With no credentials, or with `--offline`, `moss index`, `moss doc` and `moss query` keep one
index in `~/.moss/offline`. Bring your own embeddings: every document needs an `embedding`, and
`moss query --embedding` takes the query vector. Without it, only keywords rank.

```bash
moss index create notes -f docs-with-embeddings.json
moss query notes "billing" --embedding query-vector.json
moss doc add notes -f more.json
moss index delete notes
```

The index opens only for the OS user and device that created it, and in one process at a time.
Each command that opens it sends anonymous usage counts: a random device id kept in
`~/.moss/.moss-device-id`, a session id, the CLI version, and how many documents and queries
the index had. Nothing from the index leaves your device: no names, documents, queries or vectors.
A count that cannot be sent is dropped and never fails a command.
If it no longer opens, because it was copied, moved, restored from a backup or damaged,
`moss index create` replaces it and `moss index delete` removes it.
It does not run on Kubernetes, AWS Lambda or other server platforms. The built-in models, more
indexes and sync need an account. Once you have one, `moss index push` uploads the index to your
project with its embeddings:

```bash
moss login
moss keys create --project <project-id>   # export the MOSS_PROJECT_ID / MOSS_PROJECT_KEY it prints
moss index push notes --wait   # --as <name> gives the cloud index another name
```

In CI, where `CI` is set, missing credentials are an error, so a job whose secrets are unset
fails instead of building an offline index. Pass `--offline` or set `MOSS_OFFLINE=1` to use it there.

## Log in and create keys

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

```bash
# 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:

```bash
# 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:

```bash
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

```bash
# 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

# Upload the index on this device to your project
moss index push my-index --wait
```

### Document Management

```bash
# 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

```bash
# Search on this device (with an account, the index downloads first)
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"}}'

# With your own query vector, for a custom-model index: a JSON array or a file path
moss query my-index "shoes" --embedding query-vector.json

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

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

### Job Tracking

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

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

### Other

```bash
# Print version info
moss version

# Global JSON output, before the command
moss --json index list
moss --json doc get my-index
```

## Document File Format

### JSON (recommended)

```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"}}
]
```

Also supports a wrapper format: `{"documents": [...]}`.

With your own embeddings, each document carries an `embedding` of the same length:

```json
[{"id": "doc1", "text": "Machine learning fundamentals", "embedding": [0.12, -0.03, 0.41]}]
```

### CSV

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

### stdin

```bash
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 |
| `--offline` | | Use the offline index, even with credentials or in CI (or `MOSS_OFFLINE`) |
| `--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](LICENSE) for full terms. For commercial licensing, contact contact@moss.dev.

