Metadata-Version: 2.4
Name: ctxd
Version: 0.1.10
Summary: Public Python SDK and CLI for the ctxd platform.
Requires-Python: <3.13,>=3.11
Requires-Dist: fastmcp>=2.14.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.11.9
Description-Content-Type: text/markdown

# ctxd

Public Python SDK and CLI for the `ctxd` platform.

Install:

```bash
pip install ctxd
```

The SDK exposes sync and async clients:

- `Client`
- `AsyncClient`

Authentication:

1. Preferred for headless and scripts: create a user-bound API key through the authenticated application backend
2. For CLI automation, set `CTXD_API_KEY`
3. The SDK sends that key as the bearer token directly to the MCP server
4. `ctxd login` prompts for an API key interactively and stores it in plaintext in the ctxd config directory for future CLI and SDK usage
5. `ctxd status` checks whether an API key is available from the active authentication source

CLI manual:

```bash
export CTXD_API_KEY=...       # Use env-based auth for this shell/session
ctxd login                    # Prompt for an API key and store it
ctxd status                   # Check whether an API key is configured
ctxd search "text:deployment"
ctxd fetch doc-123
ctxd profile
ctxd logout                   # Remove the stored API key
```

`CTXD_API_KEY` does not require `ctxd login`. Commands such as `ctxd search`, `ctxd fetch`, and `ctxd profile` use the environment variable directly when it is set.

Stored login credentials are written in plaintext to `~/.ctxd/credentials.json` by default. Set `CTXD_CREDENTIALS_PATH` to override that location.

Base URL resolution order:

1. `base_url=` passed to the client
2. `CTXD_BASE_URL`
3. `~/.ctxd/config.json`
4. `https://mcp.ctxd.dev`

Example:

```python
from ctxd import Client

client = Client(api_key="297e24c4-4ee9-4739-828f-48f57f48ce11")

results = client.search("text:deployment application:slack")
profile = client.get_profile()
document = client.fetch_document("doc-123")
```

API key example:

```python
from ctxd import Client

client = Client(api_key="297e24c4-4ee9-4739-828f-48f57f48ce11")
results = client.search("text:deployment application:slack")
```

Async example:

```python
from ctxd import AsyncClient

async with AsyncClient(api_key="297e24c4-4ee9-4739-828f-48f57f48ce11") as client:
    results = await client.search("text:deployment")
```
