---
summary: Use scaicms-docs to push documentation from a script or CI pipeline.
title: Writing docs with an agent (Python SDK)
path: tutorials/writing-docs-with-an-agent
status: published
---

# Writing docs with an agent

Walk-through: a Python script (or an agent that can write Python) drafting
docs by talking to ScaiCMS through the official SDK.

## Install

```bash
pip install -e sdks/python-docs   # monorepo dev
# or, once published:
# pip install scaicms-docs
```

## Connect

```python
import os
from scaicms_docs import DocsClient

c = DocsClient(
    base_url=os.environ["SCAICMS_DOCS_URL"],
    api_key=os.environ["SCAICMS_DOCS_API_KEY"],
)
```

Set those env vars from the API key your admin issued (see [Connecting an
agent](/docs/scaicms/tutorials/connecting-an-agent)).

## Discover the tree

```python
for ns in c.namespaces.list():
    print(ns.slug, ns.visibility)

tree = c.pages.tree("scaicms", "v1")
def show(nodes, depth=0):
    for n in nodes:
        print("  " * depth + n.path + "  — " + n.title)
        show(n.children, depth + 1)
show(tree)
```

## Read a page (raw markdown)

```python
md = c.pages.read_raw("scaicms", "v1", "concepts/architecture")
# Now feed `md` to your LLM for transformation, summarisation, etc.
```

## Write a page

```python
saved = c.pages.upsert(
    "scaicms", "v1", "concepts/your-new-page",
    title="Your new page",
    body_md=open("draft.md").read(),
    frontmatter={"audience": "developers", "summary": "Drafted by my agent."},
    comment="Drafted by my agent at 2026-05-16",
)
print(saved.current_revision)
```

Each `upsert` is a revision. You can read the page back, mutate it, write
it again — `current_revision` increments each time.

## Search

```python
result = c.search.query("how do I shard models", namespace="scaigrid", limit=5)
for hit in result.hits:
    print(hit.path, "→", hit.anchor, hit.snippet[:80])
```

## Error handling

```python
from scaicms_docs import PermissionDenied, ValidationFailed

try:
    c.pages.upsert("locked", "v1", "x", title="Y", body_md="...")
except PermissionDenied as e:
    print("scope blocks this write:", e.message)
except ValidationFailed as e:
    print("payload rejected:", e.message)
```

## CLI

For one-off shell automation:

```bash
scaicms-docs read scaicms/v1/concepts/architecture
echo "# New page" | scaicms-docs write scaicms/v1/concepts/new --title "New"
scaicms-docs search "weaviate"
```

The agent bundle at `docs/agent-bundle/` packages this guide together with
the OpenAPI spec and MCP tool schema, ready to feed to an LLM.