docmost-cli 0.6.0__tar.gz → 0.7.0__tar.gz

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/.github/workflows/ci.yml

@@ -8,6 +8,9 @@ name: CI
 # Pins are the current majors, which target Node 24. Node 20 is deprecated and
 # is being force-migrated on the runners, so checkout@v4 / setup-python@v5 would
 # have had a shelf life.
+#
+# actionlint is downloaded and checksummed rather than run as an action, for the
+# same reason: one less third-party resolution in the path.
 
 on:
   push:
@@ -88,6 +91,34 @@ jobs:
       - name: Mypy (strict)
         run: python -m mypy src/
 
+  workflows:
+    name: lint workflows
+    runs-on: ubuntu-latest
+    # Bump both together: the checksum is for the linux_amd64 tarball of this
+    # exact version, published on the actionlint releases page.
+    env:
+      ACTIONLINT_VERSION: 1.7.12
+      ACTIONLINT_SHA256: 8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Install actionlint
+        run: |
+          set -euo pipefail
+          curl -fsSL -o actionlint.tar.gz \
+            "https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+          echo "${ACTIONLINT_SHA256}  actionlint.tar.gz" | sha256sum --check --strict
+          tar xzf actionlint.tar.gz actionlint
+
+      - name: Lint the workflows
+        # actionlint only shell-lints `run:` blocks when shellcheck is on PATH,
+        # and quietly skips them when it is not. Assert it, rather than trust the
+        # runner image to keep shipping it and lose half the coverage in silence.
+        run: |
+          set -euo pipefail
+          command -v shellcheck
+          ./actionlint -color
+
   build:
     name: build
     runs-on: ubuntu-latest

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/.github/workflows/release.yml

@@ -118,9 +118,12 @@ jobs:
           print(f"{wheel.name}: {len(pages)} man pages, licence metadata OK")
           PY
 
-      # upload@v7 and download@v8 are a matched pair: v7 uploads files directly
-      # instead of zipping them, and v8 is the major that stopped trying to
-      # un-zip a download that was never a zip. Bump them together.
+      # upload@v7 and download@v8 are a matched pair and should move together:
+      # v7 added the option to upload files as-is, and v8 is the major that
+      # stopped assuming every download is a zip.
+      #
+      # Keep `archive` at its default of true. Uploading as-is takes only a
+      # single file, and this step ships two — the wheel and the sdist.
       - uses: actions/upload-artifact@v7
         with:
           name: dist
@@ -209,7 +212,11 @@ jobs:
 
             # Only fill in notes if whoever created it left them empty —
             # never overwrite notes a human wrote by hand.
-            if [ -z "$(gh release view "$tag" --json body --jq '.body' | tr -d '[:space:]')" ]; then
+            #
+            # `body` is a nullable string, and jq renders a null as the four
+            # characters "null" — non-empty, so without the `// ""` this test
+            # reads an empty release as one a human had already written.
+            if [ -z "$(gh release view "$tag" --json body --jq '.body // ""' | tr -d '[:space:]')" ]; then
               echo "Release body is empty; filling it from CHANGELOG.md."
               gh release edit "$tag" --notes-file release-notes.md
             else

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 0.7.0 (2026-07-28)
+
+### Added
+
+- **`attachment upload <page-id> --file <path>`** — upload a file and attach it
+  to a page, closing the last "can the CLI do what the editor does" gap for
+  images. Contributed by [@amanpatel](https://github.com/amanpatel) in
+  [#1](https://github.com/glinhard/docmost-cli/pull/1).
+
+  It posts a multipart upload to `POST /files/upload`, the undocumented endpoint
+  the web editor itself uses, and prints the attachment ID to stdout with the
+  page-embeddable URL on stderr — so `ID=$(docmost-cli attachment upload ...)`
+  captures the ID alone, and the file can be embedded with
+  `![alt](/api/files/<id>/<filename>)`. The MIME type is guessed from the
+  filename and falls back to `application/octet-stream`.
+
+  Verified end to end against Docmost Community: the file uploads, the returned
+  URL renders in the page, and the endpoint answers with the attachment row
+  bare, without the `{success, status, data}` envelope every other endpoint
+  uses. The response is read both ways regardless, since an undocumented
+  endpoint's shape is not a contract. A response carrying no usable record is a
+  clear error rather than a traceback, and a filename is percent-escaped so it
+  cannot reshape the URL path.
+
+### Fixed
+
+- **`page import --title` never reached the server.** The flag was auto-detected,
+  printed in the confirmation message, and then dropped: the import endpoint has
+  no title parameter, so the page kept whatever title Docmost derived from the
+  file's first heading or its filename. The CLI said *"Imported 'X'"* about a
+  page called something else. This is the same defect as #12 one command over —
+  that fix landed inside `create_and_place_page`, which `page import` does not
+  go through. An explicit `--title` is now applied after the import; omitting it
+  still costs no extra call, since the server's own title is then the answer.
+- **`sync status` and `sync push --dry-run` listed change types in an order that
+  varied between runs.** `PageChange.changes` is a set of enum members, and
+  `Enum.__hash__` hashes the member *name* — so iteration follows Python's
+  per-process string hash seed. The same working tree could print
+  `content_changed, title_changed` on one run and `title_changed,
+  content_changed` on the next, which matters most for `--dry-run`, whose stdout
+  is the scripting-facing action plan. Both now render through one helper that
+  sorts by declaration order.
+- **`page export` could not recover from an expired session.** `post_raw` built
+  and sent its request directly instead of going through the shared retry path,
+  so the one command that uses it got no 401 re-authentication and no backoff on
+  429/5xx, unlike every other call in the CLI. On Community edition, where auth
+  *is* a refreshable session, that made an expired token a hard failure. Silent
+  endpoint probes keep their single-shot behaviour, which the
+  Enterprise/Community content fallbacks depend on.
+- `config test` no longer prints `Error: Configuration error: 1` underneath the
+  real error. It caught the `SystemExit` that `get_client()` raises after
+  reporting its own reason, and reformatted the exit *code* as the message.
+- **`page create --title` was silently discarded when the Markdown began with
+  its own heading** ([#12](https://github.com/glinhard/docmost-cli/issues/12)).
+  The import endpoint derives the page title from the first H1, and the CLI
+  never applied the explicit title afterwards — so it reported creating
+  *"agt01 — Ferdl personal agent host"* while the page persisted as *"agt01"*.
+  The title is now always applied after import, folded into the same request as
+  `--icon` so it costs one call rather than two.
+
+  Note that Docmost's import *consumes* the content's first heading — **at any
+  level** — as the page title and removes it from the body. That is unchanged
+  by this fix and applies with or without `--title`, but it means a page
+  created from `# Heading` plus `--title "Other"` keeps that text neither in
+  the body nor as the title. Put it in `--title` if you need it.
+
+  Measured against Docmost Community, not inferred: content starting `##
+  Subheading` loses that line exactly as an `# H1` does, so dropping a level is
+  not a way to keep it.
+
+  This also fixes `sync push`: a frontmatter title edited without touching the
+  body's H1 used to be ignored on page creation.
+- The man page's upload-and-embed example used `--content "![alt](...)"`, which
+  dies in an interactive `bash` with *event not found*: Markdown image syntax
+  starts with `!`, and history expansion applies inside double quotes. It now
+  pipes through `--stdin`, with the single-quote form as an alternative. Found
+  by running the documented command against a live instance.
+- `docmost-cli.1` declares the `tbl` preprocessor, so its OUTPUT CONVENTIONS
+  table renders as a table rather than as raw tbl source, and the table now fits
+  an 80-column terminal instead of overflowing it. All ten pages are clean under
+  `groff -ww`.
+
+### Changed
+
+- The release workflow no longer mistakes a null release body for hand-written
+  notes. GitHub types a release body as nullable and `jq` renders a null as the
+  text `null`, so the emptiness check read "no notes" as "notes a human wrote"
+  and skipped filling them from this file.
+- `upload-artifact` and `download-artifact` moved to their Node 24 majors, which
+  the runners had begun force-migrating.
+- CI lints the workflow files with actionlint, including shellcheck over every
+  `run:` block. Nothing checked them before, which is how an unresolvable action
+  pin, two deprecated runtimes and the null-body bug all reached `main` green.
+
+### Internal
+
+No behaviour change in any of these; they are the structural half of the same
+review that found the fixes above.
+
+- `SyncDiff.move_only` replaces three hand-written copies of "moved pages that
+  are not already being updated". Two of them compared whole `PageChange`
+  objects — every field, including the Markdown body — while the third compared
+  page IDs, so the plan `sync push` *printed* and the plan it *executed* were
+  two different computations that happened to agree.
+- `require_manifest()` in `sync/manifest.py` replaces three copies of
+  load-then-error-if-missing, and with them the two `return  # unreachable`
+  lines that followed a `NoReturn` call.
+- `output/formatter.py` now owns exactly one stdout and one stderr console, and
+  exposes `print_progress()` and `print_rendered()`. There were five consoles
+  before — two of them reached through `from ...formatter import _err_console`,
+  a private name, and two more rebuilt on every table render.
+- `sync/push.py` and `sync/pull.py` import at module level. Twenty-two imports
+  sat inside function bodies without a cycle to justify them; `sync/__init__.py`
+  imports the whole package eagerly regardless. `api/pages.py` likewise deferred
+  imports from a module it already imports on line 7.
+- `DocmostClient` gained a public `base_url` property, so `config test` stops
+  reading `client._base_url`, and a `_rebuild()` helper that replaces the
+  duplicated build-and-reauthenticate block in the retry loop.
+- `page get` fetches the page once instead of once per branch, and the nine
+  subcommand registrations in `cli/main.py` are one import block instead of nine
+  `# noqa: E402` pairs.
+
 ## 0.6.0 (2026-07-27)
 
 ### Behavior changes

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/CLAUDE.md

@@ -42,7 +42,10 @@ ruff format src/ tests/
    build derives from it) and add a `CHANGELOG.md` section.
 2. Update the `.TH` version line in all ten `man/man1/*.1` pages.
    `tests/test_docs/test_man_pages.py` fails if they drift.
-3. Merge to `main`, then push a matching tag: `git tag v0.6.0 && git push origin v0.6.0`.
+3. Merge to `main`, then push a matching tag: `git tag v0.7.0 && git push origin v0.7.0`.
+   Without a local clone, use **Releases → Draft a new release → Choose a tag →
+   create it on publish**. The workflow handles a release that already exists,
+   and fills in notes from `CHANGELOG.md` only if the body was left empty.
 
 `.github/workflows/release.yml` takes it from there: full test suite, tag ↔
 `__version__` guard, a check that the version is not already on PyPI, build,

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docmost-cli
-Version: 0.6.0
+Version: 0.7.0
 Summary: CLI tool for managing Docmost wiki instances
 Project-URL: Homepage, https://github.com/glinhard/docmost-cli
 Project-URL: Repository, https://github.com/glinhard/docmost-cli
@@ -116,7 +116,7 @@ docmost-cli page create <space-slug> --title "My Page" --file content.md
 | `docmost-cli page get <page-id>` | Get page content as Markdown (`--meta`, `--raw`) |
 | `docmost-cli page create <space-slug>` | Create a new page (`--title`, `--file`, `--stdin`) |
 | `docmost-cli page update <page-id>` | Update a page in place (`--title`, `--icon`, `--content`, `--file`, `--stdin`, `--append`, `--prepend`) |
-| `docmost-cli page delete <page-id>` | Delete a page (with confirmation, `--yes` to skip) |
+| `docmost-cli page delete <page-id>` | Delete a page (with confirmation; the global `--yes` skips it, before the subcommand: `docmost-cli --yes page delete <id>`) |
 | `docmost-cli page move <page-id>` | Move a page (`--parent`, `--space`, `--root`, `--position first\|last\|<key>`) |
 | `docmost-cli page duplicate <page-id>` | Duplicate a page |
 | `docmost-cli page copy <page-id>` | Copy a page to another space (`--space`) |
@@ -132,6 +132,7 @@ docmost-cli page create <space-slug> --title "My Page" --file content.md
 | `docmost-cli comment update <comment-id>` | Edit a comment (`--content`) |
 | `docmost-cli search query <query>` | Full-text search (`--space`, `--type`, `--json`, pagination flags) |
 | `docmost-cli attachment search <query>` | Search attachments (`--space`, `--json`, pagination flags) |
+| `docmost-cli attachment upload <page-id>` | Upload a file to a page (`--file`) |
 | `docmost-cli workspace info` | Show workspace details (`--json`, `--fields`) |
 | `docmost-cli workspace members` | List workspace members (`--json`) |
 | `docmost-cli user me` | Show authenticated user info (`--json`, `--fields`) |

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/README.md

@@ -77,7 +77,7 @@ docmost-cli page create <space-slug> --title "My Page" --file content.md
 | `docmost-cli page get <page-id>` | Get page content as Markdown (`--meta`, `--raw`) |
 | `docmost-cli page create <space-slug>` | Create a new page (`--title`, `--file`, `--stdin`) |
 | `docmost-cli page update <page-id>` | Update a page in place (`--title`, `--icon`, `--content`, `--file`, `--stdin`, `--append`, `--prepend`) |
-| `docmost-cli page delete <page-id>` | Delete a page (with confirmation, `--yes` to skip) |
+| `docmost-cli page delete <page-id>` | Delete a page (with confirmation; the global `--yes` skips it, before the subcommand: `docmost-cli --yes page delete <id>`) |
 | `docmost-cli page move <page-id>` | Move a page (`--parent`, `--space`, `--root`, `--position first\|last\|<key>`) |
 | `docmost-cli page duplicate <page-id>` | Duplicate a page |
 | `docmost-cli page copy <page-id>` | Copy a page to another space (`--space`) |
@@ -93,6 +93,7 @@ docmost-cli page create <space-slug> --title "My Page" --file content.md
 | `docmost-cli comment update <comment-id>` | Edit a comment (`--content`) |
 | `docmost-cli search query <query>` | Full-text search (`--space`, `--type`, `--json`, pagination flags) |
 | `docmost-cli attachment search <query>` | Search attachments (`--space`, `--json`, pagination flags) |
+| `docmost-cli attachment upload <page-id>` | Upload a file to a page (`--file`) |
 | `docmost-cli workspace info` | Show workspace details (`--json`, `--fields`) |
 | `docmost-cli workspace members` | List workspace members (`--json`) |
 | `docmost-cli user me` | Show authenticated user info (`--json`, `--fields`) |

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/SPECIFICATION.md

@@ -167,7 +167,7 @@ docmost-cli page get <page-id>                    # Get page content as Markdown
   --meta                                      # Prepend YAML frontmatter (id, title, space, dates)
 
 docmost-cli page create <space-slug>              # Create a new page
-  --title "Page Title"                        # Required: page title
+  --title "Page Title"                        # Required; wins over a leading heading
   --content "Markdown string"                 # Content as inline string
   --file path/to/content.md                   # Content from file
   --stdin                                     # Content from stdin
@@ -269,6 +269,8 @@ docmost-cli search <query>                        # Full-text search
 ```
 docmost-cli attachment search <query>             # Search attachments
   --space <space-slug>
+docmost-cli attachment upload <page-id>           # Upload a file to a page
+  --file <path>
 ```
 
 ### 4.8 `docmost-cli workspace`
@@ -480,6 +482,8 @@ POST /search              → {query, spaceId?, type?, limit?, cursor?}
 ```
 POST /attachments/search  → {query, spaceId?, limit?, cursor?}
 GET  /attachments/...     → file download
+POST /files/upload        → multipart {file, pageId} (undocumented; the endpoint
+                            the web editor uses for inline images/attachments)
 ```
 
 **Workspace:**
@@ -805,7 +809,7 @@ def print_error(message: str, exit_code: int = 1) -> NoReturn:
 - [x] `docmost-cli page duplicate` / `page copy`
 - [x] `docmost-cli page children` (with `--json`) / `page history` (with `--json`)
 - [x] `docmost-cli page export` / `page import`
-- [x] `docmost-cli attachment search`
+- [x] `docmost-cli attachment search` / `attachment upload`
 - [x] `docmost-cli workspace` / `docmost-cli user`
 - [x] Tree view (`--tree`) for page listing
 - [x] Pagination auto-follow for full listings
@@ -983,8 +987,25 @@ These items need investigation during implementation. Update this section as ans
       'page.<id>', …)` — **the server performs the Yjs write**. REST is
       sufficient; no WS client, no CRDT dependency.
 - [ ] **Rate limiting**: Does Docmost implement rate limiting? If so, what are the limits?
-- [ ] **Attachment upload**: Is there an API endpoint for uploading attachments, or
-      is it only available through the editor UI?
+- [x] **Attachment upload**: *Resolved*: `POST /files/upload` (multipart, fields
+      `file` + `pageId`) is the undocumented endpoint the web editor uses for
+      inline images and attachments. The page-embeddable URL is
+      `/api/files/{id}/{fileName}`. Wired up as
+      `docmost-cli attachment upload <page-id> --file <path>`.
+
+      Verified against Docmost Community on 2026-07-28: it returns the
+      attachment row **bare, without** the `{success, status, data}` envelope
+      every other endpoint uses. Observed keys:
+
+      ```
+      aiChatId, createdAt, creatorId, deletedAt, fileExt, fileName, filePath,
+      fileSize, id, mimeType, pageId, spaceId, type, updatedAt, workspaceId
+      ```
+
+      `build_attachment_url()` still routes through `unwrap_data()`, so it keeps
+      working if the endpoint is ever brought under the standard interceptor.
+      That costs nothing and the endpoint is undocumented, so its shape is not
+      contractual.
 - [x] **Space slug vs ID**: Some endpoints accept slug, others require ID.
       *Resolved*: `resolve_space_id()` helper in `api/spaces.py` calls
       `POST /spaces/info` with `{spaceSlug: slug}` and returns the ID.

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-attachment.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-attachment(1)
 .\" Source: SPECIFICATION.md section 4.6, src/docmost_cli/cli/attachment.py
-.TH DOCMOST\-CLI\-ATTACHMENT 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-ATTACHMENT 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-attachment \- attachment operations for Docmost wiki
 .SH SYNOPSIS
@@ -9,6 +9,11 @@ docmost\-cli\-attachment \- attachment operations for Docmost wiki
 .RB [ \-\-space
 .IR slug ]
 .RB [ \-\-json ]
+.PP
+.B docmost\-cli attachment upload
+.I page\-id
+.B \-\-file
+.I path
 .SH DESCRIPTION
 Commands for working with file attachments in a Docmost wiki.
 .SH SUBCOMMANDS
@@ -59,6 +64,28 @@ and
 .PP
 Default table columns: id, fileName, type.
 These affect the table only; \-\-json emits every field the server returns.
+.SS upload
+Upload a file (e.g. an image) and attach it to a page.
+.PP
+.I page\-id
+is the UUID of the page to attach the file to.
+.TP
+.BI \-\-file " path"
+Path to the local file to upload.
+The MIME type is guessed from the filename, falling back to
+.BR application/octet\-stream .
+.PP
+Prints the new attachment ID to stdout and a confirmation carrying the
+page\-embeddable URL (\fI/api/files/{id}/{fileName}\fR) to stderr, so
+.B ID=$(docmost\-cli attachment upload ...)
+captures the ID alone.
+Embed the file in a page's Markdown with
+.IR "![alt text](/api/files/<id>/<filename>)" .
+.PP
+This uses
+.IR /files/upload ,
+which is not part of Docmost's documented REST API; it is the endpoint the web
+editor itself uses for inline images and attachments.
 .SH EXAMPLES
 Search for attachments:
 .PP
@@ -75,6 +102,45 @@ Search within a space:
 $ docmost\-cli attachment search "logo" \-\-space design
 .EE
 .RE
+.PP
+Upload an image to a page:
+.PP
+.RS 4
+.EX
+$ docmost\-cli attachment upload 019e997e\-e14c\-7de7\-a35c\-15089aaa306f \\
+    \-\-file ./diagram.png
+.EE
+.RE
+.PP
+Upload an image and embed it in the page in one go:
+.PP
+.RS 4
+.EX
+$ ID=$(docmost\-cli attachment upload "$PAGE" \-\-file ./diagram.png)
+$ printf '![diagram](/api/files/%s/diagram.png)\\n' "$ID" \\
+    | docmost\-cli page update "$PAGE" \-\-append \-\-stdin
+.EE
+.RE
+.PP
+Markdown image syntax starts with
+.BR ! ,
+which an interactive
+.BR bash (1)
+treats as a history expansion inside double quotes, so
+.B \-\-content "![...]"
+fails with
+.IR "event not found" .
+Piping through
+.B \-\-stdin
+as above sidesteps the shell entirely; single quotes also work, since
+history expansion does not apply inside them:
+.PP
+.RS 4
+.EX
+$ docmost\-cli page update "$PAGE" \-\-append \\
+    \-\-content '![diagram](/api/files/'"$ID"'/diagram.png)'
+.EE
+.RE
 .SH EXIT STATUS
 See
 .BR docmost\-cli (1).

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-comment.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-comment(1)
 .\" Source: SPECIFICATION.md section 4.4, src/docmost_cli/cli/comment.py
-.TH DOCMOST\-CLI\-COMMENT 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-COMMENT 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-comment \- comment operations for Docmost wiki pages
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-config.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-config(1)
 .\" Source: SPECIFICATION.md section 4.1, src/docmost_cli/cli/config_cmd.py
-.TH DOCMOST\-CLI\-CONFIG 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-CONFIG 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-config \- manage docmost\-cli configuration
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-page.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-page(1)
 .\" Source: SPECIFICATION.md section 4.2, src/docmost_cli/cli/page.py
-.TH DOCMOST\-CLI\-PAGE 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-PAGE 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-page \- page operations for Docmost wiki
 .SH SYNOPSIS
@@ -190,6 +190,8 @@ identifies the space to create the page in.
 .BI \-\-title " title"
 Page title.
 Required.
+This is the title the page is saved with, even when the Markdown starts with a
+heading of its own.
 .TP
 .BI \-\-content " markdown"
 Inline Markdown content string.
@@ -220,6 +222,20 @@ When set, the new page is nested under this parent.
 Page icon emoji.
 .PP
 Outputs the new page ID to stdout and a confirmation message to stderr.
+.PP
+Docmost's import consumes the content's first heading \(em at any level \(em as
+the page title, and removes it from the body. That happens with or without
+.BR \-\-title ,
+so content beginning with
+.I "# Heading"
+or
+.I "## Heading"
+loses that line either way; with
+.B \-\-title
+the page is at least titled as asked, rather than after the discarded heading.
+Put the text in
+.B \-\-title
+if you need it. Starting a level lower does not preserve it.
 .SS update
 Update an existing page's title, icon, and/or content.
 .PP
@@ -418,6 +434,8 @@ Required.
 .TP
 .BI \-\-title " title"
 Override the page title.
+This is the title the page is saved with, even when the file starts with a
+heading of its own.
 If omitted, the title is auto\-detected from the filename or
 the first H1 heading in the file.
 .TP
@@ -425,6 +443,12 @@ the first H1 heading in the file.
 Parent page UUID to nest the imported page under.
 .PP
 Outputs the new page ID to stdout.
+.PP
+As with
+.BR "page create" ,
+Docmost's import consumes a leading heading: it becomes the page title and is
+removed from the body, with or without
+.BR \-\-title .
 .SH EXAMPLES
 List all pages in a space:
 .PP

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-search.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-search(1)
 .\" Source: SPECIFICATION.md section 4.5, src/docmost_cli/cli/search.py
-.TH DOCMOST\-CLI\-SEARCH 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-SEARCH 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-search \- full\-text search across a Docmost wiki
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-space.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-space(1)
 .\" Source: SPECIFICATION.md section 4.3, src/docmost_cli/cli/space.py
-.TH DOCMOST\-CLI\-SPACE 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-SPACE 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-space \- manage Docmost wiki spaces
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-sync.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-sync(1)
 .\" Source: SPECIFICATION.md section 4.10, src/docmost_cli/cli/sync_cmd.py
-.TH DOCMOST\-CLI\-SYNC 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-SYNC 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-sync \- synchronize Docmost pages with local Markdown files
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-user.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-user(1)
 .\" Source: SPECIFICATION.md section 4.8, src/docmost_cli/cli/user.py
-.TH DOCMOST\-CLI\-USER 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-USER 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-user \- current user information for Docmost
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli-workspace.1

@@ -1,6 +1,6 @@
 .\" Manual page for docmost-cli-workspace(1)
 .\" Source: SPECIFICATION.md section 4.7, src/docmost_cli/cli/workspace.py
-.TH DOCMOST\-CLI\-WORKSPACE 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI\-WORKSPACE 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli\-workspace \- Docmost workspace information
 .SH SYNOPSIS

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/man/man1/docmost-cli.1

@@ -1,6 +1,7 @@
+'\" t
 .\" Manual page for docmost-cli(1)
 .\" Source: SPECIFICATION.md, src/docmost_cli/cli/main.py
-.TH DOCMOST\-CLI 1 "2026\-03\-22" "docmost\-cli 0.6.0" "User Commands"
+.TH DOCMOST\-CLI 1 "2026\-03\-22" "docmost\-cli 0.7.0" "User Commands"
 .SH NAME
 docmost\-cli \- manage Docmost wiki instances from the terminal
 .SH SYNOPSIS
@@ -146,10 +147,10 @@ l l l.
 Command type	stdout	stderr
 _
 Content (page get)	Raw Markdown	nothing
-Content + meta (page get \-\-meta)	YAML frontmatter + Markdown	nothing
-Lists (page list, search, ...)	Rich table (curated columns) or complete JSON (\-\-json)	nothing
-Single item (user me, workspace info)	Key\-value table or JSON (\-\-json)	nothing
-Writes (page create, delete, ...)	Resource ID only	Confirmation message
+Content + meta	Frontmatter + Markdown	nothing
+Lists (page list)	Table or JSON (\-\-json)	nothing
+Single item (user me)	Key\-value or JSON	nothing
+Writes (page create)	Resource ID only	Confirmation message
 Sync status	Change summary	nothing
 Sync push \-\-dry\-run	Action plan	nothing
 Sync ops (pull, push)	nothing	Progress + summary

{docmost_cli-0.6.0 → docmost_cli-0.7.0}/src/docmost_cli/__init__.py

@@ -1,5 +1,5 @@
 """docmost-cli: CLI tool for managing Docmost wiki instances."""
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 __all__ = ["__version__"]