From e16092b5643073391b0fcc2c63106f22b21afe6a Mon Sep 17 00:00:00 2001
From: Nick Sweeting <git@sweeting.me>
Date: Fri, 14 Aug 2026 07:00:33 -0700
Subject: [PATCH] Use running Compose service for CLI examples

---
 README.md            |  7 +++----
 docker-compose.yml   |  6 +++---
 docs/Docker.md       | 26 +++++++++++++-------------
 docs/codeblocks.toml | 30 +++++++++++++++---------------
 4 files changed, 34 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 038e13c6..297cfe50 100644
--- a/README.md
+++ b/README.md
@@ -192,10 +192,9 @@ docker compose exec archivebox archivebox manage createsuperuser
 </code></pre></li>
 <li>Next steps: Log in to the Admin UI at <a href="http://admin.archivebox.localhost:8000">http://admin.archivebox.localhost:8000</a>.
 <pre lang="bash"><code style="white-space: pre-line">
-# completely optional, CLI can always be used without running a server
-# docker compose run --rm [-T] archivebox [subcommand] [--help]
-docker compose run --rm archivebox add 'https://example.com'
-docker compose run --rm archivebox help
+# run CLI commands inside the server container started above
+docker compose exec archivebox archivebox add 'https://example.com'
+docker compose exec archivebox archivebox help
 </code></pre>
 <i>For more info, see <a href="https://github.com/ArchiveBox/ArchiveBox/wiki/Install#option-a-docker--docker-compose-setup-%EF%B8%8F">Install: Docker Compose</a> in the Wiki. ➡️</i>
 </li>
diff --git a/docker-compose.yml b/docker-compose.yml
index 6006964d..12b9ee3d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -6,9 +6,9 @@
 #     docker compose exec archivebox archivebox manage createsuperuser
 #     open 'http://admin.archivebox.localhost:8000'
 
-#     docker compose run --rm archivebox add --depth=1 'https://news.ycombinator.com'
-#     docker compose run --rm -T archivebox add < ~/Downloads/bookmarks.txt
-#     docker compose run --rm archivebox help
+#     docker compose exec archivebox archivebox add --depth=1 'https://news.ycombinator.com'
+#     docker compose exec -T archivebox archivebox add < ~/Downloads/bookmarks.txt
+#     docker compose exec archivebox archivebox help
 # Documentation:
 #     https://github.com/ArchiveBox/ArchiveBox/wiki/Docker#docker-compose
 
diff --git a/docs/Docker.md b/docs/Docker.md
index 4b688f0a..fb8758c6 100644
--- a/docs/Docker.md
+++ b/docs/Docker.md
@@ -72,7 +72,7 @@ docker compose exec archivebox archivebox manage createsuperuser
 
 ArchiveBox installs and enables both ripgrep and [Sonic](https://github.com/valeriansaliou/sonic). Sonic is selected by default in the UI, while ripgrep remains available as the fallback. To select ripgrep explicitly:
 ```bash
-docker compose run --rm archivebox config --set SEARCH_BACKEND_ENGINE=ripgrep
+docker compose exec archivebox archivebox config --set SEARCH_BACKEND_ENGINE=ripgrep
 ```
 
 <br/>
@@ -85,40 +85,40 @@ See the wiki page on [Upgrading or Merging Archives: Upgrading with Docker Compo
 
 ### Usage
 
-You can use `docker compose run --rm archivebox [subcommand]` just like the non-Docker `archivebox [subcommand]` CLI.
+With the server running from the setup steps above, use `docker compose exec archivebox archivebox [subcommand]` just like the non-Docker `archivebox [subcommand]` CLI. If the server is stopped, use `docker compose run --rm archivebox [subcommand]` instead.
 
 First, make sure you're `cd`'ed into the same folder as your `docker-compose.yml` file (e.g. `~/archivebox`):
 ```bash
-docker compose run --rm archivebox help
+docker compose exec archivebox archivebox help
 ```
 
 To add an individual URL, pass it in as an arg or via stdin:
 ```bash
-docker compose run --rm archivebox add 'https://example.com'
+docker compose exec archivebox archivebox add 'https://example.com'
 # OR
-echo 'https://example.com' | docker compose run --rm -T archivebox add
+echo 'https://example.com' | docker compose exec -T archivebox archivebox add
 ```
 
 To add multiple URLs at once, pipe them in via stdin, or place them in a file inside `./data/sources` so that ArchiveBox can access it from within the container:
 ```bash
 # pipe URLs in from a file outside Docker
-docker compose run --rm -T archivebox add < ~/Downloads/example_urls.txt
+docker compose exec -T archivebox archivebox add < ~/Downloads/example_urls.txt
 
 # OR ingest URLs from a file mounted inside Docker
-docker compose run --rm archivebox add --depth=1 /data/sources/example_urls.txt
+docker compose exec archivebox archivebox add --depth=1 /data/sources/example_urls.txt
 
 # OR pipe in URLs from a remote source
-curl 'https://example.com/some/rss/feed.xml' | docker compose run --rm -T archivebox add
-docker compose run --rm archivebox add --depth=1 'https://example.com/some/rss/feed.xml'
+curl 'https://example.com/some/rss/feed.xml' | docker compose exec -T archivebox archivebox add
+docker compose exec archivebox archivebox add --depth=1 'https://example.com/some/rss/feed.xml'
 ```
 
 The `--depth=1` flag tells ArchiveBox to look inside the provided source and archive all the URLs within:
 ```bash
 # this archives just the RSS file itself (probably not what you want)
-docker compose run --rm archivebox add 'https://example.com/some/feed.rss'
+docker compose exec archivebox archivebox add 'https://example.com/some/feed.rss'
 
 # this archives the RSS feed file + all the URLs mentioned inside of it
-docker compose run --rm archivebox add --depth=1 'https://example.com/some/feed.rss'
+docker compose exec archivebox archivebox add --depth=1 'https://example.com/some/feed.rss'
 ```
 
 <br/>
@@ -144,12 +144,12 @@ ArchiveBox running with `docker compose` accepts all the same config options as
 
 The recommended way configure ArchiveBox in Docker Compose is using `archivebox config --set ...` or by editing `ArchiveBox.conf`.
 ```bash
-docker compose run --rm archivebox config --set TIMEOUT=120
+docker compose exec archivebox archivebox config --set TIMEOUT=120
 # OR edit ./data/ArchiveBox.conf and add this under its existing [ARCHIVING_CONFIG] section:
 TIMEOUT=120
 
 # plugin-specific options work the same way (see https://archivebox.github.io/abx-plugins/)
-docker compose run --rm archivebox config --set YTDLP_MAX_SIZE=750m
+docker compose exec archivebox archivebox config --set YTDLP_MAX_SIZE=750m
 ```
 This will apply the config to all containers or archivebox instances that access the collection.
 
diff --git a/docs/codeblocks.toml b/docs/codeblocks.toml
index 11160c6c..cf1f5e67 100644
--- a/docs/codeblocks.toml
+++ b/docs/codeblocks.toml
@@ -8,7 +8,7 @@ version = 2
 "12a201778c81f310-1" = "illustration"
 "dfce88ac5547f8e1-1" = "illustration"
 "220882ff87e9c738-1" = "run"
-"100c85d878e5ec52-1" = "illustration"
+"698f2b0f88796c9b-1" = "illustration"
 "1754491b1b6255de-1" = "illustration"
 "778c693286d7b895-1" = "illustration"
 "16f90085b2eb8756-1" = "illustration"
@@ -108,13 +108,13 @@ version = 2
 # docs/Docker.md
 "03a42395e6560eba-1" = "illustration"
 "4deb738714bdbd33-1" = "illustration"
-"10f9ca01b3b7a305-1" = "run"
-"fef4f0641483ee49-1" = "run"
-"8104bfe431c6b914-1" = "run"
-"df0dbbd212722e34-1" = "illustration"
-"b10a271100fee968-1" = "illustration"
+"affb9c5d5980ed1c-1" = "run"
+"0e9c1f41ef579e79-1" = "run"
+"746a3e228d29f9d2-1" = "run"
+"66a7d54ea81d64dc-1" = "illustration"
+"aa4884ebe3101cf6-1" = "illustration"
 "150ae2c7f6d012ab-1" = "illustration"
-"646dda5284de16a5-1" = "run"
+"8d86727108f1dbad-1" = "run"
 "6bcb6c2e8770907a-1" = "illustration"
 "d093b42a06e0485e-1" = "illustration"
 "6353a7cf3014612e-1" = "illustration"
@@ -292,10 +292,10 @@ version = 2
 "70389ddb24a77820-1" = "system"
 "c4266755c0748aa0-1" = "collection"
 "ea6d6196f0985d3c-1" = "collection"
-"10f9ca01b3b7a305-1" = "docker"
-"fef4f0641483ee49-1" = "docker"
-"8104bfe431c6b914-1" = "docker"
-"646dda5284de16a5-1" = "docker"
+"affb9c5d5980ed1c-1" = "docker"
+"0e9c1f41ef579e79-1" = "docker"
+"746a3e228d29f9d2-1" = "docker"
+"8d86727108f1dbad-1" = "docker"
 "c8df632a4f4e3100-1" = "system"
 "4d29a8d4b3902ab3-1" = "system"
 "73f9f36a369f2398-1" = "system"
@@ -372,10 +372,10 @@ version = 2
 "70389ddb24a77820-1" = "ubuntu"
 "c4266755c0748aa0-1" = "ubuntu"
 "ea6d6196f0985d3c-1" = "ubuntu"
-"10f9ca01b3b7a305-1" = "docker"
-"fef4f0641483ee49-1" = "docker"
-"8104bfe431c6b914-1" = "docker"
-"646dda5284de16a5-1" = "docker"
+"affb9c5d5980ed1c-1" = "docker"
+"0e9c1f41ef579e79-1" = "docker"
+"746a3e228d29f9d2-1" = "docker"
+"8d86727108f1dbad-1" = "docker"
 "c8df632a4f4e3100-1" = "macos"
 "4d29a8d4b3902ab3-1" = "macos"
 "73f9f36a369f2398-1" = "root"