bookstack-cli 0.1.0__py3-none-any.whl

bookstack_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: bookstack-cli
+Version: 0.1.0
+Summary: CLI for coding agents to interact with a BookStack wiki via its REST API
+Author: Michael Zehrer
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mzehrer/bookstack-cli
+Project-URL: Source, https://github.com/mzehrer/bookstack-cli
+Project-URL: Issues, https://github.com/mzehrer/bookstack-cli/issues
+Project-URL: Documentation, https://github.com/mzehrer/bookstack-cli#readme
+Keywords: bookstack,wiki,cli,api,documentation
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Utilities
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typer>=0.15
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=7.1.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.36.2; extra == "dev"
+Requires-Dist: ruff>=0.15.19; extra == "dev"
+
+# bookstack-cli
+
+[![Python](https://img.shields.io/badge/python-≥3.14-blue)]()
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)]()
+
+CLI for coding agents to interact with a [BookStack](https://www.bookstackapp.com/) wiki via its REST API. All output is JSON — built for LLM pipelines, not humans.
+
+```bash
+bookstack books list | jq '. | length'
+bookstack pages get 42 | jq '.html[:200]'
+bookstack search query "api docs" | jq '.[] | {name, type, score}'
+bookstack test
+```
+
+## Install
+
+```bash
+# One-liner (no clone needed)
+uv tool install bookstack-cli          # from PyPI, once published
+# or from source:
+# uv tool install git+https://github.com/mzehrer/bookstack-cli.git
+
+# Or clone for development
+cd bookstack-cli
+make init          # or: uv sync
+```
+
+## Setup
+
+```bash
+bookstack auth           # interactive — prompts for URL, token, secret
+
+# If public web URL differs from API (e.g. behind OAuth proxy):
+bookstack auth --resolve-url https://wiki.public.example.com
+```
+
+### Config File
+
+Saved to `~/.config/bookstack-cli/config.toml`:
+
+```toml
+[connection]
+url = "http://10.0.0.1:8080"                    # API endpoint (internal)
+resolve_url = "https://wiki.public.example.com"  # public web URL (optional)
+token_id = "<your-token-id>"
+token_secret = "<your-token-secret>"
+```
+
+`resolve_url` is optional — defaults to `url` if not set.
+
+### Env Vars (override file)
+
+```bash
+export BOOKSTACK_URL=http://10.0.0.1:8080
+export BOOKSTACK_RESOLVE_URL=https://wiki.example.com
+export BOOKSTACK_TOKEN_ID=<your-token-id>
+export BOOKSTACK_TOKEN_SECRET=<your-token-secret>
+```
+
+Precedence: env vars > config file > error.
+
+[See auth docs →](docs/authentication.md)
+
+## Usage
+
+```
+$ bookstack --help
+
+╭─ Commands ───────────────────────────────────────╮
+│ auth         Save connection credentials.         │
+│ config       Manage connection config.            │
+│ test         Test connection to BookStack.        │
+│ shelves      Manage bookshelves.                  │
+│ books        Manage books.                        │
+│ chapters     Manage chapters.                     │
+│ pages        Manage pages.                        │
+│ attachments  Manage attachments.                  │
+│ users        Manage users (admin).                │
+│ roles        Manage roles (admin).                │
+│ search       Search content.                      │
+╰───────────────────────────────────────────────────╯
+```
+
+### Common Workflows
+
+```bash
+# Test connection
+bookstack test
+
+# List all books
+bookstack books list
+
+# Get a specific page
+bookstack pages get 42
+
+# Create a page from file
+bookstack pages create "My Page" --book-id 1 --markdown-file content.md
+
+# Pipe multi-line content
+cat content.md | bookstack pages create "Piped Page" --book-id 1
+
+# Append text to existing page
+bookstack pages update 42 --append "New section at the end"
+
+# Resolve web URL to page
+bookstack pages resolve-url "https://wiki/books/my-book/page/my-page"
+
+# Import markdown with images
+bookstack pages import --file article.md --book-id 1 --name "Article"
+
+# Search across all content
+bookstack search query "installation guide"
+
+# List attachments on a page
+bookstack attachments list --page-id 10
+
+# Upload a file attachment
+bookstack attachments upload --name "Report" --page-id 42 --file report.pdf
+
+# Create a shelf and assign books
+bookstack shelves create "Dev Docs"
+bookstack shelves update 1 "Dev Docs" --books "10,20,30"
+
+# Update entity
+bookstack books update 1 "New Title"
+```
+
+## Features
+
+| Feature | Status |
+|---|---|
+| Shelves CRUD (+ book assignment) | ✅ |
+| Books CRUD | ✅ |
+| Chapters CRUD | ✅ |
+| Pages CRUD (partial update, append, move) | ✅ |
+| Markdown import with image handling | ✅ |
+| Web URL → API ID resolution | ✅ |
+| Attachments (link + file upload) | ✅ |
+| Search across content | ✅ |
+| Users/Roles (admin) | ✅ |
+| Async HTTP with retry/backoff | ✅ |
+| Auto-pagination (client-side filtering) | ✅ |
+| Config test / connection check | ✅ |
+| JSON-only output | ✅ |
+
+## Project Layout
+
+```
+bookstack-cli/
+├── bookstack_cli/
+│   ├── client.py        # HTTP client, auth, rate-limit, pagination
+│   ├── config.py        # Env vars → ~/.config/bookstack-cli/config.toml
+│   ├── exceptions.py    # Typed error hierarchy
+│   ├── models.py        # Pydantic models for all entities
+│   ├── main.py          # Typer CLI entry point
+│   └── resources/       # One module per entity
+│       ├── books.py
+│       ├── chapters.py
+│       ├── pages.py
+│       ├── shelves.py
+│       ├── attachments.py
+│       ├── search.py
+│       ├── users.py
+│       ├── roles.py
+│       ├── revisions.py
+│       └── tags.py
+├── tests/               # 130+ tests
+├── docs/                # Detailed docs
+├── skill/               # Pi agent skill
+├── Makefile             # init/test/lint/format/run
+└── pyproject.toml
+```
+
+## Documentation
+
+| File | What |
+|---|---|
+| [docs/overview.md](docs/overview.md) | Architecture, goals, scope |
+| [docs/authentication.md](docs/authentication.md) | Token setup, env config, security |
+| [docs/api-reference.md](docs/api-reference.md) | All endpoints, schemas, pagination |
+| [docs/integration-guide.md](docs/integration-guide.md) | Hacking BookStack, injections, webhooks |
+| [docs/research.md](docs/research.md) | Raw API research findings |
+| [skill/SKILL.md](skill/SKILL.md) | Agent skill for pi/coding agents |
+| [AGENT.md](AGENT.md) | TDD protocol for this project |
+
+## Design
+
+- **Async from day one** — `httpx.AsyncClient` with retry + exponential backoff on 429s
+- **Pydantic v2** — typed models for every entity, validated responses
+- **Agent-friendly output** — everything is JSON via stdout, no interactive prompts
+- **Resource-per-file** — one module per entity, consistent `list/get/create/update/delete` signatures
+- **Config cascade** — env vars > `~/.config/bookstack-cli/config.toml` > error
+- **TDD** — 130 tests, red/green/refactor cycle (see [AGENT.md](AGENT.md))
+
+## License
+
+MIT

bookstack_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+bookstack_cli/__init__.py,sha256=ur3yl7JmqmkVCIQPKSnRZDK_mi-xDrf53SILXSWSb_Q,104
+bookstack_cli/client.py,sha256=RzIr8nh52yEzEit7is6sacizYrOTLVW7eRBdc5BsqOw,6963
+bookstack_cli/config.py,sha256=n5wB1f66MzZDt_KcCjj9P8GG3AMXVsQXyWZTKUkWKZw,3780
+bookstack_cli/exceptions.py,sha256=EHeCf0d_uZAltR94-au3EfnqOYKPu_s1tUfw_bH3aL8,1146
+bookstack_cli/main.py,sha256=n-Ss8eta47Ey1VZiguFO79sF_n0xXrr95G6Z0P6WbeM,28577
+bookstack_cli/models.py,sha256=-dy_iElFF25FeTK-ott4GG7XWJGlguBaLL4c6i3jUKU,6651
+bookstack_cli/resources/__init__.py,sha256=5Sf-wWATnfShJclo4rctFXuBeMoi9IIPC3QcZB57yaA,51
+bookstack_cli/resources/attachments.py,sha256=tVX2AcMzRqV3_t8Ebd6GHh2SZ0T7FgpFiBQz6JxAjGI,2746
+bookstack_cli/resources/books.py,sha256=EjBYoptKrDBrqIQ-WZHhi2yH6fCGy1ZbLEeQ8-mvDV0,1934
+bookstack_cli/resources/chapters.py,sha256=WQHF2s-P9NyZOivvlABqG_IiSkQ9tE_dkWxD5He7qic,1481
+bookstack_cli/resources/pages.py,sha256=5yOfi0l5eDdm20XsxcuU1BDc0YCoTFpRfP2cwmLzg2A,13119
+bookstack_cli/resources/revisions.py,sha256=J5iaeqV0oD7a_21NryemN5tXVS1Cwj_3kvmyOYEkuxU,895
+bookstack_cli/resources/roles.py,sha256=QCe5aLKrjV_-StyDtSbO1RshuJfKFYpItRj2ozAZVTM,989
+bookstack_cli/resources/search.py,sha256=wSZr5xA-ko2GgfOaOz-SN5kZtK_Vy0CSgQse4oNF1ao,575
+bookstack_cli/resources/shelves.py,sha256=dS6I4FLqpfEZktsGFXQwR9S1kGdjREeLpSByGqkrqCE,1777
+bookstack_cli/resources/tags.py,sha256=_yzOtvGD5XabkDeUteLlsAzxqo2cyuiwRjq_Y5jFGw0,401
+bookstack_cli/resources/users.py,sha256=eOO2ZBIyvOP2WuUfgShUdlYTqSKsjzjIB81FhH0Aq1M,1179
+bookstack_cli-0.1.0.dist-info/METADATA,sha256=4icOXetFu8jU9FuEFehamvV2w7D6gAzZp8q7ggfpWLQ,7573
+bookstack_cli-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+bookstack_cli-0.1.0.dist-info/entry_points.txt,sha256=vZkvtx0avoCMBXvVIEgcfdSC_HHKcSaL9wfLIXbwAHI,53
+bookstack_cli-0.1.0.dist-info/top_level.txt,sha256=nAnl3On-KzJVLYmvdsmyV4kW5fjB4nPKyQk6JFfFCSY,14
+bookstack_cli-0.1.0.dist-info/RECORD,,

bookstack_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bookstack_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bookstack = bookstack_cli.main:app

bookstack_cli-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bookstack_cli