ctxd 0.1.1

Public Python SDK and CLI for the ctxd platform.

ctxd

Public Python SDK and CLI for the ctxd platform.

Install:

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:

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:

from ctxd import AsyncClient

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