# docstream-cli

Command-line interface for the Docstream Context-Docs server.

## Installation

### From the private devpi registry (recommended for other hosts)

```bash
uv pip install --index-url "https://pypi.registry.hochguertel.work/root/dev/+simple/" docstream-cli
```

Or with pip:

```bash
pip install --index-url "https://pypi.registry.hochguertel.work/root/dev/+simple/" docstream-cli
```

### From the monorepo (development)

```bash
cd /path/to/docstream
uv sync --all-packages
```

### Standalone with uvx

```bash
uvx --index-url "https://pypi.registry.hochguertel.work/root/dev/+simple/" docstream-cli --help
```

## Usage

The CLI communicates with a running Docstream server (combined or split mode). By default it connects to `http://localhost:49202/api/v1`. Override with `--api-url` or the `DOCSTREAM_API_URL` environment variable.

```bash
# Create a context
docstream create --context my-docs

# Add a local source
docstream add --context my-docs --source local:/path/to/markdown --alias docs

# Add a remote (SSH) source
docstream add --context my-docs --source ssh:hostA:/path/to/docs --alias remote-docs

# List all contexts
docstream list

# Reload a context (invalidate render cache)
docstream reload --context my-docs

# Remove a source
docstream remove --context my-docs --slug docs

# Delete a context
docstream delete --context my-docs

# Check service status
docstream status
```

### Start/stop the service

```bash
# Start the background service (uvicorn)
docstream start

# Stop the background service
docstream stop
```

### Renderer overrides

```bash
# Create a context with a specific Markdown engine
docstream create --context my-docs --md-engine python-markdown

# Add a source with a specific highlight engine
docstream add --context my-docs --source local:/path/to/docs --hl-engine none
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `DOCSTREAM_API_URL` | `http://localhost:49202/api/v1` | API base URL |

## Dependencies

- `docstream-api-client` — generated Python SDK (OpenAPI)
- `docstream-api-sdk` — generated Pydantic models (TypeSpec)
- `typer` — CLI framework
- `httpx` — HTTP client
- `rich` — terminal formatting
