Metadata-Version: 2.4
Name: ctxd
Version: 0.1.1
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. Run `ctxd login` with the CLI to store OAuth credentials in a secure local store
2. The CLI starts a device-style login session through the backend auth API
3. The browser flow continues on `https://app.ctxd.dev/cli-login`, so login can finish on a different machine than the terminal session
4. The backend dynamically registers the CLI session with the MCP authorization server and completes the OAuth callback server-side
5. The SDK keeps only non-secret metadata in `~/.ctxd/config.json`
6. The SDK reads the stored access token and refreshes it automatically when needed
7. Tokens are loaded from the OS keychain when available, otherwise from an encrypted local credential store unlocked with a passphrase entered interactively or provided through `CTXD_PASSPHRASE`

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

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

Async example:

```python
from ctxd import AsyncClient

async with AsyncClient() as client:
    results = await client.search("text:deployment")
```
