outline-py

Python client and CLI for the Outline API.

PyPI distribution: outline-python Import package: outline_py CLI command: outline-py

outline-py provides:

• A typed synchronous Python client
• A typed asynchronous Python client
• A Typer-based CLI
• Full current Outline API surface coverage, plus typed convenience commands for common workflows

Install

uv sync --extra dev

For consumers:

pip install outline-python

Setup

uv venv .venv
uv sync --extra dev
source .venv/bin/activate

Python usage

from outline_py import OutlineClient

with OutlineClient(api_key="ol_api_...", base_url="https://app.getoutline.com/api") as client:
    response = client.documents.search(query="hiring", limit=10)
    print(response.data)

Async Python usage

import asyncio

from outline_py import AsyncOutlineClient


async def main() -> None:
    async with AsyncOutlineClient(api_key="ol_api_...") as client:
        response = await client.documents.search(query="hiring", limit=10)
        print(response.data)


asyncio.run(main())

CLI usage

The CLI exposes two layers:

1. Typed commands for common workflows
2. Full API coverage through grouped --payload commands

outline-py common whoami
outline-py common search "hiring" --limit 10
outline-py common doc-info hDYep1TPAM
outline-py common doc-show hDYep1TPAM
outline-py common collection-create Engineering
outline-py common share-create 3b6d8f9a-...

The grouped commands remain available for the full surface:

outline-py auth info
outline-py documents search --payload '{"query":"hiring","limit":10}'
outline-py collections create --payload '{"name":"Engineering"}'

Configuration can be provided through flags or environment variables:

export OUTLINE_API_KEY="ol_api_..."
export OUTLINE_BASE_URL="https://app.getoutline.com/api"
outline-py documents info --payload '{"id":"doc_123"}'
outline-py common doc-info doc_123

The --payload value uses the Python client's snake_case parameter names.

Development

uv run ruff check .
uv run pytest
uv build

Release

The repository includes a GitHub Actions workflow at .github/workflows/workflow.yaml that publishes to PyPI when you push a tag matching v*.

Example:

git tag v0.1.2
git push origin v0.1.2

For publishing to work, configure PyPI Trusted Publishing for the singularcurio/outline-py GitHub repository.