[RFC] BookStack API CLI (not a feature request, code already written) #3149

New Issue

OVERLORD · 2026-02-05T06:05:34+03:00

OVERLORD commented

2026-02-05 06:05:34 +03:00

Originally created by @Yetangitu on GitHub (Sep 17, 2022).

Describe the feature you'd like

This is not a feature request since I already created the necessary tooling to provide easy command line access to the API.

Here's the repo:

https://github.com/Yetangitu/bs

Here's what it does:

List available books

bs books list

Again, this time 500 results, start at offset #1000

bs books list -c 500 -o 1000

Show details for page with id 12345

bs pages read -i 12345

Create a book with title "Book of Books" and description "A book about
books" with a cover image of a Pozzebok and two tags

bs books create -n "Book of Books" -d "A book about books" \
-I /tmp/pozzebok.png -t 'subject=a book on books;cover=image of a pozzebok'

Search for this book

bs search -q "Book of Books"

Delete the book with ID=23456

bs books delete -i 23456

Create a chapter in book #4242

bs chapters create -b 4242 -n "First Chapter" -d "Obviously the first chapter"

Create page and attach it to chapter #456, using markdown. Notice the
markdown content is spread over several lines with empty lines in between
and that double quotes in the content are escaped.

bs pages create -c 456 -n "Page of Pages" -m "#Page of Pages
This is the first line of the first page.

And this is the second one, a _masterwork_ in the making.

Don't forget to \"escape\" double quotes"

Delete that useless page you just made

bs pages delete -i 66753

Create another page, this time reading markdown/html page content from a file

bs pages create -c 456 -n "Page the second" -m @/home/me/Documents/magnum_opus.md
bs pages create -c 456 -n "Page the second" -h @/home/me/Documents/magnum_opus.html

Export a book/chapter/page to PDF/HTML/Markdown, redirecting output to a file

bs books export-pdf -i 6679 > book_6679.pdf
bs chapters export-html -i 112 > chapter_112.html
bs page export-markdown -i 5665 > page_5665.md

Attach a file to a page with ID 5678

bs attachments create -n "Deep Image" -u 5678 -f /tmp/deepimage.png

Attach a link to the same page

bs attachments create -n "Deeper Image" -u 5678 -l 'https://example.org/deeperimage.png'

List the first 200 attachments

bs attachments list -c 200

Create a shelf and put a few books on it

bs shelves create -n "Billy" -d "IKEA Bookshelf" -B 456,654,345,3343 -I /tmp/billy.jpg

List the contents of the recycle bin, showing 100 entries

bs recycle-bin list -c 100

Restore entry #34 from the recycle bin

bs recycle-bin restore -i 34

Create a user

bs users create -n "Billy Bob" -e "billybob@example.org" -L "Klingon" -p "b1llyb0b123"

Edit the bs config file

bs config

Describe the benefits this would bring to existing BookStack users

I made this tool to make it easier to batch-create books/chapters/pages for conference session recordings. Instead of having to manually edit page after page or rigging up a whole tool chain to use one of the example API scripts this tool makes it possible to use standard *nix CLI tools to manage a BookStack instance. All API endpoints are supported so anything that BookStack supports is accessible.

Here's some pseudocode showing how to create a set of pages in a book based on the contents of a series of directories, one page per directory, using information gleaned from session.json files in those directories:

find some/directory -type d|while read d;do
    IFS=$'\n' read -d '' name description doc_link doc_title <<< "$(jq '.title, .description, .documentation.link, .documentation.title' "$d/session.json")"
    page_id=$(bs pages create -c 123 -n "$name" -m "$description"|jq '.id')
    bs attachments create -u "$page_id" -n "$doc_title" -l "$doc_link"
done

This snippet creates pages for a whole conference worth of sessions in a few seconds with session documentation attached to to those pages.

Can the goal of this request already be achieved via other means?

Yes, that is why this is a RFC instead of a feature request.

https://github.com/Yetangitu/bs

Pull this repo and give it a try. This being version 0.0.1 there will probably be some rough edges but it Works For Me™. I suspect others are interested in this tool as well so I can create a PR to integrate it somewhere, the question is - where? In the api-scripts repo? In the main repo?

Have you searched for an existing open/closed issue?

I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

0 to 6 months

Additional context

No response

Originally created by @Yetangitu on GitHub (Sep 17, 2022). ### Describe the feature you'd like This is not a feature request since I already created the necessary tooling to provide easy command line access to the API. Here's the repo: https://github.com/Yetangitu/bs Here's what it does: List available books bs books list Again, this time 500 results, start at offset #1000 bs books list -c 500 -o 1000 Show details for page with id 12345 bs pages read -i 12345 Create a book with title "Book of Books" and description "A book about books" with a cover image of a Pozzebok and two tags bs books create -n "Book of Books" -d "A book about books" \ -I /tmp/pozzebok.png -t 'subject=a book on books;cover=image of a pozzebok' Search for this book bs search -q "Book of Books" Delete the book with ID=23456 bs books delete -i 23456 Create a chapter in book #4242 bs chapters create -b 4242 -n "First Chapter" -d "Obviously the first chapter" Create page and attach it to chapter #456, using markdown. Notice the markdown content is spread over several lines with empty lines in between and that double quotes in the content are escaped. bs pages create -c 456 -n "Page of Pages" -m "#Page of Pages This is the first line of the first page. And this is the second one, a _masterwork_ in the making. Don't forget to \"escape\" double quotes" Delete that useless page you just made bs pages delete -i 66753 Create another page, this time reading markdown/html page content from a file bs pages create -c 456 -n "Page the second" -m @/home/me/Documents/magnum_opus.md bs pages create -c 456 -n "Page the second" -h @/home/me/Documents/magnum_opus.html Export a book/chapter/page to PDF/HTML/Markdown, redirecting output to a file bs books export-pdf -i 6679 > book_6679.pdf bs chapters export-html -i 112 > chapter_112.html bs page export-markdown -i 5665 > page_5665.md Attach a file to a page with ID 5678 bs attachments create -n "Deep Image" -u 5678 -f /tmp/deepimage.png Attach a link to the same page bs attachments create -n "Deeper Image" -u 5678 -l 'https://example.org/deeperimage.png' List the first 200 attachments bs attachments list -c 200 Create a shelf and put a few books on it bs shelves create -n "Billy" -d "IKEA Bookshelf" -B 456,654,345,3343 -I /tmp/billy.jpg List the contents of the recycle bin, showing 100 entries bs recycle-bin list -c 100 Restore entry #34 from the recycle bin bs recycle-bin restore -i 34 Create a user bs users create -n "Billy Bob" -e "billybob@example.org" -L "Klingon" -p "b1llyb0b123" Edit the _bs_ config file bs config ### Describe the benefits this would bring to existing BookStack users I made this tool to make it easier to batch-create books/chapters/pages for conference session recordings. Instead of having to manually edit page after page or rigging up a whole tool chain to use one of the example API scripts this tool makes it possible to use standard _*nix_ CLI tools to manage a _BookStack_ instance. All API endpoints are supported so anything that BookStack supports is accessible. Here's some pseudocode showing how to create a set of pages in a book based on the contents of a series of directories, one page per directory, using information gleaned from `session.json` files in those directories: ``` find some/directory -type d|while read d;do IFS=$'\n' read -d '' name description doc_link doc_title <<< "$(jq '.title, .description, .documentation.link, .documentation.title' "$d/session.json")" page_id=$(bs pages create -c 123 -n "$name" -m "$description"|jq '.id') bs attachments create -u "$page_id" -n "$doc_title" -l "$doc_link" done ``` This snippet creates pages for a whole conference worth of sessions in a few seconds with session documentation attached to to those pages. ### Can the goal of this request already be achieved via other means? Yes, that is why this is a RFC instead of a feature request. https://github.com/Yetangitu/bs Pull this repo and give it a try. This being version 0.0.1 there will probably be some rough edges but it _Works For Me™_. I suspect others are interested in this tool as well so I can create a PR to integrate it somewhere, the question is - where? In the api-scripts repo? In the main repo? ### Have you searched for an existing open/closed issue? - [X] I have searched for existing issues and none cover my fundemental request ### How long have you been using BookStack? 0 to 6 months ### Additional context _No response_

OVERLORD added the ☕ Open to discussion ❓ Question labels 2026-02-05 06:05:34 +03:00

OVERLORD closed this issue

2026-02-05 06:05:39 +03:00

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#3149