Metadata-Version: 2.4
Name: ctxd
Version: 0.1.6
Summary: Public Python SDK and CLI for the ctxd platform.
Requires-Python: <3.13,>=3.11
Requires-Dist: cryptography>=44.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.7.0
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. Provide it with `Client(api_key=...)` or `CTXD_API_KEY`
3. The SDK sends that key as the bearer token directly to the MCP server
4. `ctxd login` is still supported for interactive local OAuth login
5. If `CTXD_API_KEY` is set and you run `ctxd login`, the CLI first validates the key with `get_profile()`. If valid, it skips OAuth and reports that you are already authenticated. If invalid, it warns and asks whether to continue with interactive login.

Base URL resolution order:

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

Auth API URL resolution order:

1. `CTXD_AUTH_API_URL`
2. `https://api.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")
```
