Metadata-Version: 2.4
Name: moss-cli
Version: 0.2.0
Summary: Command-line interface for Moss semantic search
Author-email: "InferEdge Inc." <contact@usemoss.dev>
Keywords: search,semantic,cli,moss
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-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: moss>=1.0.0
Requires-Dist: typer>=0.26.8
Requires-Dist: rich>=15.0.0
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: black<26,>=25.9.0; extra == "dev"
Requires-Dist: isort<8,>=7.0.0; extra == "dev"
Requires-Dist: flake8>=7.3.0; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Requires-Dist: build>=1.5.0; extra == "dev"
Requires-Dist: twine>=6.2.0; extra == "dev"
Dynamic: license-file

# 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 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.

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

### 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 (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

```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
moss index list --json
moss doc get my-index --json
```

## 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": [...]}`.

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