mdview-cli 0.1.0__tar.gz → 1.0.0__tar.gz

mdview_cli-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: CLI
+
+on:
+  push:
+    tags:
+      - "v*"
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e '.[test]'
+      - run: python -m pytest tests/test_cli.py
+
+  e2e-free-tools:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e '.[test]'
+      - run: python -m pytest tests/e2e
+
+  publish:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [test, e2e-free-tools]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

mdview_cli-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

mdview_cli-1.0.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mdview-cli
+Version: 1.0.0
+Summary: Iterate on Markdown and verify every revision with mdview.io
+License-Expression: MIT
+Project-URL: Homepage, https://mdview.io
+Project-URL: Repository, https://github.com/gogainda/mdview-cli
+Project-URL: Issues, https://github.com/gogainda/mdview-cli/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# mdv — preview Markdown files from your terminal
+
+`mdv` renders a Markdown file the way it should look — headings, tables, code,
+Mermaid diagrams — and opens it in your browser. One command, no account, no
+configuration.
+
+```bash
+uv tool install mdview-cli    # or: pipx install mdview-cli, pip install mdview-cli
+mdv notes.md
+```
+
+Homebrew users:
+
+```bash
+brew install gogainda/tap/mdview-cli
+```
+
+That's the whole workflow: `mdv FILE.md` publishes the file to
+[mdview.io](https://mdview.io), opens the rendered page, and prints a link you
+can send to anyone. Anonymous previews last 30 days and take files up to 2 MB.
+
+## Two ways to preview
+
+**Shareable preview (default).** `mdv FILE.md` is shorthand for `mdv preview
+FILE.md`. The title comes from the first `#` heading, or pass your own:
+
+```bash
+mdv notes.md
+mdv preview notes.md --title "Design notes"
+mdv preview notes.md --json     # print the share URLs as JSON, don't open a browser
+```
+
+**Local-only preview.** `mdv open` uploads nothing: it packs the file into the
+URL itself and rendering happens entirely in your browser. Use it for drafts
+that shouldn't leave your machine.
+
+```bash
+mdv open notes.md
+```
+
+## Iterating on one document
+
+Previews are throwaway: every run mints a new link. When you keep working on
+the same file — a spec, an architecture doc, a report — you want the opposite:
+one stable URL whose content follows your edits, and a check that every
+revision still renders cleanly.
+
+Set up a free mdview.io CLI token once, then it's one command per iteration:
+
+```bash
+mdv keys set          # once (or set MDVIEW_TOKEN in CI)
+mdv sync spec.md      # publish this revision, verify it, auto-repair broken diagrams
+```
+
+While you iterate, the document lives at its **private** `/p/` page — only
+you, signed in, can see it, and the URL stays the same forever. Every sync
+shows the fixed, renderable version there. Broken Mermaid diagrams are
+repaired automatically and the fix is written back into your file (the
+original is kept as a timestamped backup); only documents that can't be
+repaired exit `1`.
+
+When — and only when — you decide to publish, make it public; and grab a PDF
+at any point:
+
+```bash
+mdv share spec.md     # mint the public /s/ link (from then on it follows your syncs)
+mdv export spec.md    # render the current revision to spec.pdf
+```
+
+Useful around the loop:
+
+```bash
+mdv sync spec.md --no-fix     # fast sync: skip auto-repair, just report failures
+mdv export spec.md --no-sync  # PDF of the last synced revision; local edits stay private
+mdv list                      # all saved documents with their URLs
+mdv unlink spec.md            # forget the file↔document link; the document stays online
+```
+
+Nothing is public until you run `mdv share`. After that, the public page
+serves the last synced revision — mid-edit local changes still stay private
+until you sync. `mdv fix FILE --local` repairs a file in place without
+creating a saved document (free accounts share the daily Quick Fix limit;
+Pro is unlimited).
+
+### Example session
+
+A real session, working on a doc whose Mermaid diagrams start out broken:
+
+```console
+$ mdv sync spec.md                 # iterate — the broken flowchart is auto-repaired (~30s)
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (1 diagrams, 0 tables)
+
+$ vim spec.md                      # …add two sections, each with a (broken) diagram…
+$ mdv sync spec.md                 # same doc, all three diagrams repaired and verified
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (3 diagrams, 0 tables)
+
+$ mdv share spec.md                # happy with it — make it public
+https://mdview.io/s/9a2b8fb1
+
+$ mdv export spec.md               # …and hand over a PDF
+PDF: spec.pdf
+```
+
+Two commands did all the work: `mdv sync` after every editing round, and
+`mdv share` once at the end. The fixes were written back into `spec.md`
+(originals in timestamped backups, so you can review what the repair
+changed — worth a glance before sharing, since a repair is guaranteed to
+render but not to read your mind), the private URL never changed, and the
+public link didn't exist until it was asked for.
+
+**When this flow fits:** a document that lives longer than one paste — specs,
+architecture docs, reports, runbooks, agent-written docs you refine over
+hours or days. Use it when reviewers follow one link that must always show
+the latest good revision, when a PDF has to be producible at any moment, or
+in CI as a docs gate (`mdv sync --no-fix` exits `1` on broken diagrams
+without editing anything). For a one-off snapshot, `mdv preview` is enough;
+for reading a local file without uploading it, use `mdv open`.
+
+## Reference
+
+| Command | Token | What it does |
+|---|---|---|
+| `mdv FILE.md` / `mdv preview` | no | Publish anonymously, open the rendered page (30-day link) |
+| `mdv open` | no | Render locally in the browser; nothing is uploaded |
+| `mdv sync` | yes | Update a saved document at its private /p/ URL, verify + auto-repair |
+| `mdv share` | yes | Make a synced document public at its /s/ URL |
+| `mdv verify` | yes | Re-check rendering of a synced document |
+| `mdv fix` | yes | Repair broken Mermaid diagrams, with a local backup |
+| `mdv export` | yes | Export a synced document to PDF |
+| `mdv list` | yes | List saved documents |
+| `mdv unlink` | no | Remove the local file↔document association |
+| `mdv keys set/list/path/unset` | — | Manage the stored CLI token |
+
+Exit codes: `0` success, `1` document doesn't render cleanly, `2` usage error,
+`3` mdview.io error.
+
+Environment: `MDVIEW_TOKEN` supplies the token without storing it (ideal for
+CI); `MDVIEW_BASE_URL` points the CLI at another server.

mdview_cli-1.0.0/README.md

@@ -0,0 +1,142 @@
+# mdv — preview Markdown files from your terminal
+
+`mdv` renders a Markdown file the way it should look — headings, tables, code,
+Mermaid diagrams — and opens it in your browser. One command, no account, no
+configuration.
+
+```bash
+uv tool install mdview-cli    # or: pipx install mdview-cli, pip install mdview-cli
+mdv notes.md
+```
+
+Homebrew users:
+
+```bash
+brew install gogainda/tap/mdview-cli
+```
+
+That's the whole workflow: `mdv FILE.md` publishes the file to
+[mdview.io](https://mdview.io), opens the rendered page, and prints a link you
+can send to anyone. Anonymous previews last 30 days and take files up to 2 MB.
+
+## Two ways to preview
+
+**Shareable preview (default).** `mdv FILE.md` is shorthand for `mdv preview
+FILE.md`. The title comes from the first `#` heading, or pass your own:
+
+```bash
+mdv notes.md
+mdv preview notes.md --title "Design notes"
+mdv preview notes.md --json     # print the share URLs as JSON, don't open a browser
+```
+
+**Local-only preview.** `mdv open` uploads nothing: it packs the file into the
+URL itself and rendering happens entirely in your browser. Use it for drafts
+that shouldn't leave your machine.
+
+```bash
+mdv open notes.md
+```
+
+## Iterating on one document
+
+Previews are throwaway: every run mints a new link. When you keep working on
+the same file — a spec, an architecture doc, a report — you want the opposite:
+one stable URL whose content follows your edits, and a check that every
+revision still renders cleanly.
+
+Set up a free mdview.io CLI token once, then it's one command per iteration:
+
+```bash
+mdv keys set          # once (or set MDVIEW_TOKEN in CI)
+mdv sync spec.md      # publish this revision, verify it, auto-repair broken diagrams
+```
+
+While you iterate, the document lives at its **private** `/p/` page — only
+you, signed in, can see it, and the URL stays the same forever. Every sync
+shows the fixed, renderable version there. Broken Mermaid diagrams are
+repaired automatically and the fix is written back into your file (the
+original is kept as a timestamped backup); only documents that can't be
+repaired exit `1`.
+
+When — and only when — you decide to publish, make it public; and grab a PDF
+at any point:
+
+```bash
+mdv share spec.md     # mint the public /s/ link (from then on it follows your syncs)
+mdv export spec.md    # render the current revision to spec.pdf
+```
+
+Useful around the loop:
+
+```bash
+mdv sync spec.md --no-fix     # fast sync: skip auto-repair, just report failures
+mdv export spec.md --no-sync  # PDF of the last synced revision; local edits stay private
+mdv list                      # all saved documents with their URLs
+mdv unlink spec.md            # forget the file↔document link; the document stays online
+```
+
+Nothing is public until you run `mdv share`. After that, the public page
+serves the last synced revision — mid-edit local changes still stay private
+until you sync. `mdv fix FILE --local` repairs a file in place without
+creating a saved document (free accounts share the daily Quick Fix limit;
+Pro is unlimited).
+
+### Example session
+
+A real session, working on a doc whose Mermaid diagrams start out broken:
+
+```console
+$ mdv sync spec.md                 # iterate — the broken flowchart is auto-repaired (~30s)
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (1 diagrams, 0 tables)
+
+$ vim spec.md                      # …add two sections, each with a (broken) diagram…
+$ mdv sync spec.md                 # same doc, all three diagrams repaired and verified
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (3 diagrams, 0 tables)
+
+$ mdv share spec.md                # happy with it — make it public
+https://mdview.io/s/9a2b8fb1
+
+$ mdv export spec.md               # …and hand over a PDF
+PDF: spec.pdf
+```
+
+Two commands did all the work: `mdv sync` after every editing round, and
+`mdv share` once at the end. The fixes were written back into `spec.md`
+(originals in timestamped backups, so you can review what the repair
+changed — worth a glance before sharing, since a repair is guaranteed to
+render but not to read your mind), the private URL never changed, and the
+public link didn't exist until it was asked for.
+
+**When this flow fits:** a document that lives longer than one paste — specs,
+architecture docs, reports, runbooks, agent-written docs you refine over
+hours or days. Use it when reviewers follow one link that must always show
+the latest good revision, when a PDF has to be producible at any moment, or
+in CI as a docs gate (`mdv sync --no-fix` exits `1` on broken diagrams
+without editing anything). For a one-off snapshot, `mdv preview` is enough;
+for reading a local file without uploading it, use `mdv open`.
+
+## Reference
+
+| Command | Token | What it does |
+|---|---|---|
+| `mdv FILE.md` / `mdv preview` | no | Publish anonymously, open the rendered page (30-day link) |
+| `mdv open` | no | Render locally in the browser; nothing is uploaded |
+| `mdv sync` | yes | Update a saved document at its private /p/ URL, verify + auto-repair |
+| `mdv share` | yes | Make a synced document public at its /s/ URL |
+| `mdv verify` | yes | Re-check rendering of a synced document |
+| `mdv fix` | yes | Repair broken Mermaid diagrams, with a local backup |
+| `mdv export` | yes | Export a synced document to PDF |
+| `mdv list` | yes | List saved documents |
+| `mdv unlink` | no | Remove the local file↔document association |
+| `mdv keys set/list/path/unset` | — | Manage the stored CLI token |
+
+Exit codes: `0` success, `1` document doesn't render cleanly, `2` usage error,
+`3` mdview.io error.
+
+Environment: `MDVIEW_TOKEN` supplies the token without storing it (ideal for
+CI); `MDVIEW_BASE_URL` points the CLI at another server.

{mdview_cli-0.1.0 → mdview_cli-1.0.0}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools>=69"]
+requires = ["setuptools>=69", "setuptools-scm>=8"]
 build-backend = "setuptools.build_meta"
 
 [project]
@@ -29,8 +29,8 @@ mdv = "mdview_cli.cli:cli"
 [tool.setuptools.packages.find]
 where = ["src"]
 
-[tool.setuptools.dynamic]
-version = {attr = "mdview_cli.__version__"}
+[tool.setuptools_scm]
+fallback_version = "0.0.0"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{mdview_cli-0.1.0 → mdview_cli-1.0.0}/src/mdview_cli/api.py

@@ -51,6 +51,9 @@ class MdviewApi:
     def fix(self, document_id):
         return self.request("POST", f"/api/documents/{document_id}/fix/diagrams", json={}).json()
 
+    def fix_markdown(self, content):
+        return self.request("POST", "/api/documents/fix/diagrams", json={"content": content}).json()
+
     def export_pdf(self, document_id):
         return self.request("GET", f"/api/documents/{document_id}/export/pdf").content
 

{mdview_cli-0.1.0 → mdview_cli-1.0.0}/src/mdview_cli/cli.py

@@ -77,6 +77,7 @@ def result_payload(document_id, share, report, created=False):
     return {
         "document_id": document_id,
         "created": created,
+        "url": f"{base_url()}/p/{document_id}",
         "share_url": share_url(share) if share else None,
         "renderable": verdict(report),
         "diagrams": report.get("diagrams", {}),
@@ -90,6 +91,8 @@ def print_result(payload, as_json=False, *, check=True):
         click.echo(json.dumps(payload, separators=(",", ":")))
     else:
         click.echo(f"Document: {payload['document_id']}")
+        if payload.get("url"):
+            click.echo(f"Private: {payload['url']}")
         if payload.get("share_url"):
             click.echo(f"Share: {payload['share_url']}")
         diagrams = payload.get("diagrams") or {}
@@ -109,7 +112,7 @@ def print_result(payload, as_json=False, *, check=True):
         raise click.exceptions.Exit(1)
 
 
-def sync_file(path: Path, *, api=None, state=None, title=None, document_id=None, share=True, verify=True):
+def sync_file(path: Path, *, api=None, state=None, title=None, document_id=None, share=False, verify=True):
     if not path.is_file():
         raise click.UsageError(f"File not found: {path}")
     markdown = path.read_text(encoding="utf-8")
@@ -198,19 +201,56 @@ def keys_list():
     click.echo("default" if get_token() else "No token configured.")
 
 
+def repair_synced_file(file, api, state, document_id):
+    repaired = api.fix(document_id)
+    markdown = repaired.get("markdown")
+    if markdown is None:
+        raise ServiceError("The repair response did not include Markdown.")
+    backup = backup_file(file, document_id)
+    atomic_write(file, markdown)
+    payload = sync_file(file, api=api, state=state)
+    payload["backup"] = str(backup)
+    payload["fixed"] = repaired.get("diagrams", {}).get("fixed", 0)
+    return payload
+
+
 @cli.command("sync")
 @click.argument("file", type=click.Path(path_type=Path))
+@click.option("--no-fix", "no_fix", is_flag=True, help="Skip auto-repair; just report failing diagrams.")
 @click.option("--title")
 @click.option("--id", "document_id")
-@click.option("--no-share", is_flag=True)
 @click.option("--json", "as_json", is_flag=True)
 @service_errors
-def sync_command(file, title, document_id, no_share, as_json):
-    """Update FILE, preserve its URL, and verify PDF rendering."""
-    payload = sync_file(file, title=title, document_id=document_id, share=not no_share)
+def sync_command(file, no_fix, title, document_id, as_json):
+    """Sync FILE to its private /p/ page, repairing broken diagrams on the way."""
+    api = api_for_token()
+    state = DocumentState()
+    payload = sync_file(file, api=api, state=state, title=title, document_id=document_id)
+    if not payload["renderable"] and not no_fix:
+        try:
+            payload = repair_synced_file(file, api, state, payload["document_id"])
+        except ApiError as error:
+            click.secho(f"Auto-repair unavailable: {error}", fg="yellow", err=True)
     print_result(payload, as_json)
 
 
+@cli.command("share")
+@click.argument("file", required=False, type=click.Path(path_type=Path))
+@click.option("--id", "document_id")
+@service_errors
+def share_command(file, document_id):
+    """Make FILE's document public and print its share URL."""
+    state = DocumentState()
+    association = state.get(base_url(), file) if file else None
+    document_id = document_id or (association and association["document_id"])
+    if not document_id:
+        raise click.UsageError("Provide a synced FILE or --id.")
+    sid = share_id(api_for_token().share(document_id))
+    if file:
+        state.put(base_url(), file, document_id, sid, None)
+    click.echo(share_url(sid))
+
+
 @cli.command("verify")
 @click.argument("file", required=False, type=click.Path(path_type=Path))
 @click.option("--id", "document_id")
@@ -227,42 +267,77 @@ def verify_command(file, document_id, status, as_json):
     print_result(payload, as_json)
 
 
+def backup_file(path: Path, key: str) -> Path:
+    backup_dir = data_dir() / "backups" / key
+    backup_dir.mkdir(parents=True, exist_ok=True)
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
+    backup = backup_dir / f"{stamp}-{path.name}"
+    shutil.copy2(path, backup)
+    return backup
+
+
 @cli.command("fix")
 @click.argument("file", type=click.Path(path_type=Path))
+@click.option("--local", "local_only", is_flag=True, help="Repair the file in place without creating a saved document.")
 @click.option("--json", "as_json", is_flag=True)
 @service_errors
-def fix_command(file, as_json):
+def fix_command(file, local_only, as_json):
+    if local_only:
+        if not file.is_file():
+            raise click.UsageError(f"File not found: {file}")
+        report = api_for_token().fix_markdown(file.read_text(encoding="utf-8"))
+        diagrams = report.get("diagrams", {})
+        payload = {
+            "renderable": bool(report.get("renderable")),
+            "fixed": diagrams.get("fixed", 0),
+            "remaining": diagrams.get("remaining", 0),
+            "backup": None,
+        }
+        markdown = report.get("markdown")
+        if payload["fixed"] and markdown:
+            payload["backup"] = str(backup_file(file, "local"))
+            atomic_write(file, markdown)
+        if as_json:
+            click.echo(json.dumps(payload, separators=(",", ":")))
+        else:
+            if payload["backup"]:
+                click.echo(f"Fixed {payload['fixed']} diagram(s); backup: {payload['backup']}")
+            if payload["renderable"]:
+                click.secho("Renderable: yes", fg="green")
+            else:
+                click.secho(f"Renderable: no ({payload['remaining']} diagrams still failing)", fg="red", err=True)
+        if not payload["renderable"]:
+            raise click.exceptions.Exit(1)
+        return
     api = api_for_token()
     state = DocumentState()
     initial = sync_file(file, api=api, state=state, verify=False)
-    repaired = api.fix(initial["document_id"])
-    markdown = repaired.get("markdown")
-    if markdown is None:
-        raise ServiceError("The repair response did not include Markdown.")
-    backup_dir = data_dir() / "backups" / initial["document_id"]
-    backup_dir.mkdir(parents=True, exist_ok=True)
-    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
-    backup = backup_dir / f"{stamp}-{file.name}"
-    shutil.copy2(file, backup)
-    atomic_write(file, markdown)
-    payload = sync_file(file, api=api, state=state)
-    payload["backup"] = str(backup)
-    payload["fixed"] = repaired.get("diagrams", {}).get("fixed", 0)
+    payload = repair_synced_file(file, api, state, initial["document_id"])
     print_result(payload, as_json)
 
 
 @cli.command("export")
-@click.argument("file", type=click.Path(path_type=Path))
+@click.argument("file", required=False, type=click.Path(path_type=Path))
 @click.option("-o", "--output", type=click.Path(path_type=Path))
+@click.option("--id", "document_id")
+@click.option("--no-sync", "no_sync", is_flag=True, help="Export the published document as-is, without uploading local changes.")
 @click.option("--force", is_flag=True)
 @service_errors
-def export_command(file, output, force):
+def export_command(file, output, document_id, no_sync, force):
     api = api_for_token()
-    payload = sync_file(file, api=api)
+    if no_sync or file is None:
+        association = DocumentState().get(base_url(), file) if file else None
+        document_id = document_id or (association and association["document_id"])
+        if not document_id:
+            raise click.UsageError("Provide an associated FILE or --id.")
+        report = api.verify(document_id)
+        payload = result_payload(document_id, association and association["share_id"], report)
+    else:
+        payload = sync_file(file, api=api, document_id=document_id)
     print_result(payload, check=False)
     if not payload["renderable"] and not force:
         raise click.ClickException("Document is not Renderable; use --force to export anyway.")
-    output = output or file.with_suffix(".pdf")
+    output = output or (file.with_suffix(".pdf") if file else Path(f"{payload['document_id']}.pdf"))
     pdf = api.export_pdf(payload["document_id"])
     output.parent.mkdir(parents=True, exist_ok=True)
     atomic_write(output, pdf)

mdview_cli-1.0.0/src/mdview_cli.egg-info/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mdview-cli
+Version: 1.0.0
+Summary: Iterate on Markdown and verify every revision with mdview.io
+License-Expression: MIT
+Project-URL: Homepage, https://mdview.io
+Project-URL: Repository, https://github.com/gogainda/mdview-cli
+Project-URL: Issues, https://github.com/gogainda/mdview-cli/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Dynamic: license-file
+
+# mdv — preview Markdown files from your terminal
+
+`mdv` renders a Markdown file the way it should look — headings, tables, code,
+Mermaid diagrams — and opens it in your browser. One command, no account, no
+configuration.
+
+```bash
+uv tool install mdview-cli    # or: pipx install mdview-cli, pip install mdview-cli
+mdv notes.md
+```
+
+Homebrew users:
+
+```bash
+brew install gogainda/tap/mdview-cli
+```
+
+That's the whole workflow: `mdv FILE.md` publishes the file to
+[mdview.io](https://mdview.io), opens the rendered page, and prints a link you
+can send to anyone. Anonymous previews last 30 days and take files up to 2 MB.
+
+## Two ways to preview
+
+**Shareable preview (default).** `mdv FILE.md` is shorthand for `mdv preview
+FILE.md`. The title comes from the first `#` heading, or pass your own:
+
+```bash
+mdv notes.md
+mdv preview notes.md --title "Design notes"
+mdv preview notes.md --json     # print the share URLs as JSON, don't open a browser
+```
+
+**Local-only preview.** `mdv open` uploads nothing: it packs the file into the
+URL itself and rendering happens entirely in your browser. Use it for drafts
+that shouldn't leave your machine.
+
+```bash
+mdv open notes.md
+```
+
+## Iterating on one document
+
+Previews are throwaway: every run mints a new link. When you keep working on
+the same file — a spec, an architecture doc, a report — you want the opposite:
+one stable URL whose content follows your edits, and a check that every
+revision still renders cleanly.
+
+Set up a free mdview.io CLI token once, then it's one command per iteration:
+
+```bash
+mdv keys set          # once (or set MDVIEW_TOKEN in CI)
+mdv sync spec.md      # publish this revision, verify it, auto-repair broken diagrams
+```
+
+While you iterate, the document lives at its **private** `/p/` page — only
+you, signed in, can see it, and the URL stays the same forever. Every sync
+shows the fixed, renderable version there. Broken Mermaid diagrams are
+repaired automatically and the fix is written back into your file (the
+original is kept as a timestamped backup); only documents that can't be
+repaired exit `1`.
+
+When — and only when — you decide to publish, make it public; and grab a PDF
+at any point:
+
+```bash
+mdv share spec.md     # mint the public /s/ link (from then on it follows your syncs)
+mdv export spec.md    # render the current revision to spec.pdf
+```
+
+Useful around the loop:
+
+```bash
+mdv sync spec.md --no-fix     # fast sync: skip auto-repair, just report failures
+mdv export spec.md --no-sync  # PDF of the last synced revision; local edits stay private
+mdv list                      # all saved documents with their URLs
+mdv unlink spec.md            # forget the file↔document link; the document stays online
+```
+
+Nothing is public until you run `mdv share`. After that, the public page
+serves the last synced revision — mid-edit local changes still stay private
+until you sync. `mdv fix FILE --local` repairs a file in place without
+creating a saved document (free accounts share the daily Quick Fix limit;
+Pro is unlimited).
+
+### Example session
+
+A real session, working on a doc whose Mermaid diagrams start out broken:
+
+```console
+$ mdv sync spec.md                 # iterate — the broken flowchart is auto-repaired (~30s)
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (1 diagrams, 0 tables)
+
+$ vim spec.md                      # …add two sections, each with a (broken) diagram…
+$ mdv sync spec.md                 # same doc, all three diagrams repaired and verified
+Document: 8be0be9198400443
+Private: https://mdview.io/p/8be0be9198400443
+Renderable: yes (3 diagrams, 0 tables)
+
+$ mdv share spec.md                # happy with it — make it public
+https://mdview.io/s/9a2b8fb1
+
+$ mdv export spec.md               # …and hand over a PDF
+PDF: spec.pdf
+```
+
+Two commands did all the work: `mdv sync` after every editing round, and
+`mdv share` once at the end. The fixes were written back into `spec.md`
+(originals in timestamped backups, so you can review what the repair
+changed — worth a glance before sharing, since a repair is guaranteed to
+render but not to read your mind), the private URL never changed, and the
+public link didn't exist until it was asked for.
+
+**When this flow fits:** a document that lives longer than one paste — specs,
+architecture docs, reports, runbooks, agent-written docs you refine over
+hours or days. Use it when reviewers follow one link that must always show
+the latest good revision, when a PDF has to be producible at any moment, or
+in CI as a docs gate (`mdv sync --no-fix` exits `1` on broken diagrams
+without editing anything). For a one-off snapshot, `mdv preview` is enough;
+for reading a local file without uploading it, use `mdv open`.
+
+## Reference
+
+| Command | Token | What it does |
+|---|---|---|
+| `mdv FILE.md` / `mdv preview` | no | Publish anonymously, open the rendered page (30-day link) |
+| `mdv open` | no | Render locally in the browser; nothing is uploaded |
+| `mdv sync` | yes | Update a saved document at its private /p/ URL, verify + auto-repair |
+| `mdv share` | yes | Make a synced document public at its /s/ URL |
+| `mdv verify` | yes | Re-check rendering of a synced document |
+| `mdv fix` | yes | Repair broken Mermaid diagrams, with a local backup |
+| `mdv export` | yes | Export a synced document to PDF |
+| `mdv list` | yes | List saved documents |
+| `mdv unlink` | no | Remove the local file↔document association |
+| `mdv keys set/list/path/unset` | — | Manage the stored CLI token |
+
+Exit codes: `0` success, `1` document doesn't render cleanly, `2` usage error,
+`3` mdview.io error.
+
+Environment: `MDVIEW_TOKEN` supplies the token without storing it (ideal for
+CI); `MDVIEW_BASE_URL` points the CLI at another server.

{mdview_cli-0.1.0 → mdview_cli-1.0.0}/src/mdview_cli.egg-info/SOURCES.txt

@@ -1,6 +1,8 @@
+.gitignore
 LICENSE
 README.md
 pyproject.toml
+.github/workflows/release.yml
 src/mdview_cli/__init__.py
 src/mdview_cli/api.py
 src/mdview_cli/cli.py
@@ -11,5 +13,8 @@ src/mdview_cli.egg-info/SOURCES.txt
 src/mdview_cli.egg-info/dependency_links.txt
 src/mdview_cli.egg-info/entry_points.txt
 src/mdview_cli.egg-info/requires.txt
+src/mdview_cli.egg-info/scm_file_list.json
+src/mdview_cli.egg-info/scm_version.json
 src/mdview_cli.egg-info/top_level.txt
-tests/test_cli.py
+tests/test_cli.py
+tests/e2e/test_free_tools.py

mdview_cli-1.0.0/src/mdview_cli.egg-info/scm_file_list.json

@@ -0,0 +1,16 @@
+{
+  "files": [
+    ".gitignore",
+    "README.md",
+    "pyproject.toml",
+    "LICENSE",
+    "src/mdview_cli/api.py",
+    "src/mdview_cli/state.py",
+    "src/mdview_cli/config.py",
+    "src/mdview_cli/cli.py",
+    "src/mdview_cli/__init__.py",
+    ".github/workflows/release.yml",
+    "tests/test_cli.py",
+    "tests/e2e/test_free_tools.py"
+  ]
+}

mdview_cli-1.0.0/src/mdview_cli.egg-info/scm_version.json

@@ -0,0 +1,8 @@
+{
+  "tag": "1.0.0",
+  "distance": 0,
+  "node": "g3c5d7f760b99e8bc0a5b93e1cf747fd01ac52421",
+  "dirty": false,
+  "branch": "HEAD",
+  "node_date": "2026-07-18"
+}

mdview_cli-1.0.0/tests/e2e/test_free_tools.py

@@ -0,0 +1,75 @@
+import base64
+import os
+import shutil
+import subprocess
+import zipfile
+from io import BytesIO
+from pathlib import Path
+
+
+def run_mdv(*arguments, env):
+    executable = shutil.which("mdv")
+    assert executable, "mdv must be installed before running E2E tests"
+    return subprocess.run(
+        [executable, *map(str, arguments)],
+        env=env,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def token_free_env(tmp_path):
+    env = os.environ.copy()
+    env.pop("MDVIEW_TOKEN", None)
+    env.pop("MDVIEW_BASE_URL", None)
+    env["MDVIEW_CONFIG_DIR"] = str(tmp_path / "config")
+    env["MDVIEW_DATA_DIR"] = str(tmp_path / "data")
+    return env
+
+
+def test_open_hands_the_exact_markdown_to_the_browser_without_a_token(tmp_path):
+    markdown = "# Architecture\n\n```mermaid\nflowchart LR\n  A --> B\n```\n"
+    document = tmp_path / "architecture.md"
+    document.write_text(markdown, encoding="utf-8")
+    captured_url = tmp_path / "browser-url.txt"
+    browser = tmp_path / "capture-browser"
+    browser.write_text(
+        "#!/usr/bin/env python3\n"
+        "import os, pathlib, sys\n"
+        "pathlib.Path(os.environ['MDV_CAPTURE_URL']).write_text(sys.argv[1])\n",
+        encoding="utf-8",
+    )
+    browser.chmod(0o755)
+    env = token_free_env(tmp_path)
+    env["BROWSER"] = str(browser)
+    env["MDV_CAPTURE_URL"] = str(captured_url)
+
+    result = run_mdv("open", document, env=env)
+
+    assert result.returncode == 0, result.stderr
+    assert f"Opened {document}" in result.stdout
+    url = captured_url.read_text(encoding="utf-8")
+    prefix = "https://mdview.io/#mvd=zip:"
+    assert url.startswith(prefix)
+    archive = zipfile.ZipFile(BytesIO(base64.b64decode(url.removeprefix(prefix))))
+    assert archive.namelist() == ["architecture.md"]
+    assert archive.read("architecture.md").decode("utf-8") == markdown
+
+
+def test_help_version_and_key_inspection_work_without_a_token(tmp_path):
+    env = token_free_env(tmp_path)
+
+    help_result = run_mdv("--help", env=env)
+    version_result = run_mdv("--version", env=env)
+    keys_result = run_mdv("keys", "list", env=env)
+    path_result = run_mdv("keys", "path", env=env)
+
+    assert help_result.returncode == 0
+    assert "open" in help_result.stdout
+    assert version_result.returncode == 0
+    assert version_result.stdout.startswith("mdv, version ")
+    assert keys_result.returncode == 0
+    assert keys_result.stdout.strip() == "No token configured."
+    assert path_result.returncode == 0
+    assert Path(path_result.stdout.strip()) == tmp_path / "config" / "keys.json"

{mdview_cli-0.1.0 → mdview_cli-1.0.0}/tests/test_cli.py

@@ -13,6 +13,7 @@ class FakeApi:
         self.created = 0
         self.updated = 0
         self.verified = 0
+        self.shared = 0
         self.missing_on_update = False
 
     def create(self, title, content):
@@ -27,6 +28,7 @@ class FakeApi:
         return {"ok": True, "updated_at": "two"}
 
     def share(self, document_id):
+        self.shared += 1
         return {"shortId": "share123"}
 
     def verify(self, document_id, status=False):
@@ -45,6 +47,16 @@ class FakeApi:
         self.renderable = True
         return {"markdown": "# Fixed\n\n```mermaid\ngraph TD; A-->B\n```\n", "diagrams": {"fixed": 1}}
 
+    def export_pdf(self, document_id):
+        return b"%PDF-1.4 rendered"
+
+    def fix_markdown(self, content):
+        return {
+            "renderable": True,
+            "markdown": "# Fixed locally\n",
+            "diagrams": {"total": 1, "failing_before": 1, "fixed": 1, "remaining": 0},
+        }
+
 
 def configure(monkeypatch, tmp_path, api):
     monkeypatch.setenv("MDVIEW_TOKEN", "mdv1_test")
@@ -66,14 +78,20 @@ def test_sync_creates_once_then_updates_and_always_verifies(monkeypatch, tmp_pat
 
     assert first.exit_code == 0
     assert second.exit_code == 0
-    assert "https://mdview.io/s/share123" in second.output
+    assert "https://mdview.io/p/doc123" in second.output
     assert api.created == 1
     assert api.updated == 1
     assert api.verified == 2
+    assert api.shared == 0
 
 
-def test_sync_reports_broken_diagram_and_exits_one(monkeypatch, tmp_path):
+def test_sync_reports_broken_diagram_and_exits_one_when_repair_unavailable(monkeypatch, tmp_path):
     api = FakeApi(renderable=False)
+
+    def quota_exhausted(document_id):
+        raise ApiError("Daily Quick Fix limit reached. Upgrade to Pro for unlimited fixes.", 402)
+
+    api.fix = quota_exhausted
     configure(monkeypatch, tmp_path, api)
     document = tmp_path / "broken.md"
     document.write_text("# Broken\n", encoding="utf-8")
@@ -81,8 +99,8 @@ def test_sync_reports_broken_diagram_and_exits_one(monkeypatch, tmp_path):
     result = CliRunner().invoke(cli, ["sync", str(document)])
 
     assert result.exit_code == 1
+    assert "Auto-repair unavailable" in result.output
     assert "Diagram 0: Parse error" in result.output
-    assert "mdv fix FILE" in result.output
 
 
 def test_sync_recreates_a_deleted_associated_document(monkeypatch, tmp_path):
@@ -168,6 +186,86 @@ def test_unknown_command_still_errors(tmp_path):
     assert "No such command" in result.output
 
 
+def test_share_publishes_on_request_and_sync_stays_private_until_then(monkeypatch, tmp_path):
+    api = FakeApi()
+    configure(monkeypatch, tmp_path, api)
+    document = tmp_path / "doc.md"
+    document.write_text("# Doc\n", encoding="utf-8")
+    runner = CliRunner()
+    assert runner.invoke(cli, ["sync", str(document)]).exit_code == 0
+    assert api.shared == 0
+
+    shared = runner.invoke(cli, ["share", str(document)])
+    resynced = runner.invoke(cli, ["sync", str(document)])
+
+    assert shared.exit_code == 0
+    assert shared.output.strip() == "https://mdview.io/s/share123"
+    assert api.shared == 1
+    assert "Share: https://mdview.io/s/share123" in resynced.output
+
+
+def test_sync_no_fix_skips_repair_and_exits_one(monkeypatch, tmp_path):
+    api = FakeApi(renderable=False)
+    configure(monkeypatch, tmp_path, api)
+    document = tmp_path / "broken.md"
+    original = "# Broken\n\n```mermaid\nnope\n```\n"
+    document.write_text(original, encoding="utf-8")
+
+    result = CliRunner().invoke(cli, ["sync", str(document), "--no-fix"])
+
+    assert result.exit_code == 1
+    assert "Diagram 0: Parse error" in result.output
+    assert document.read_text(encoding="utf-8") == original
+
+
+def test_sync_auto_repairs_broken_diagrams_and_exits_zero(monkeypatch, tmp_path):
+    api = FakeApi(renderable=False)
+    configure(monkeypatch, tmp_path, api)
+    document = tmp_path / "broken.md"
+    document.write_text("# Broken\n\n```mermaid\nnope\n```\n", encoding="utf-8")
+
+    result = CliRunner().invoke(cli, ["sync", str(document)])
+
+    assert result.exit_code == 0
+    assert document.read_text(encoding="utf-8").startswith("# Fixed")
+    assert "Renderable: yes" in result.output
+
+
+def test_export_no_sync_exports_published_doc_without_uploading(monkeypatch, tmp_path):
+    api = FakeApi()
+    configure(monkeypatch, tmp_path, api)
+    document = tmp_path / "doc.md"
+    document.write_text("# Doc\n", encoding="utf-8")
+    runner = CliRunner()
+    assert runner.invoke(cli, ["sync", str(document)]).exit_code == 0
+    document.write_text("# Broken WIP edit\n", encoding="utf-8")
+
+    result = runner.invoke(cli, ["export", str(document), "--no-sync"])
+
+    assert result.exit_code == 0
+    assert (tmp_path / "doc.pdf").read_bytes() == b"%PDF-1.4 rendered"
+    assert api.created == 1 and api.updated == 0
+
+
+def test_fix_local_rewrites_file_without_syncing(monkeypatch, tmp_path):
+    api = FakeApi()
+    configure(monkeypatch, tmp_path, api)
+    document = tmp_path / "broken.md"
+    original = "# Broken\n\n```mermaid\nnope\n```\n"
+    document.write_text(original, encoding="utf-8")
+
+    result = CliRunner().invoke(cli, ["fix", str(document), "--local", "--json"])
+
+    assert result.exit_code == 0
+    payload = json.loads(result.output)
+    assert payload["fixed"] == 1
+    assert document.read_text(encoding="utf-8") == "# Fixed locally\n"
+    assert Path(payload["backup"]).read_text(encoding="utf-8") == original
+    assert api.created == 0
+    assert api.updated == 0
+    assert api.verified == 0
+
+
 def test_fix_backs_up_rewrites_resyncs_and_verifies(monkeypatch, tmp_path):
     api = FakeApi(renderable=False)
     configure(monkeypatch, tmp_path, api)

mdview_cli-0.1.0/PKG-INFO

@@ -1,63 +0,0 @@
-Metadata-Version: 2.4
-Name: mdview-cli
-Version: 0.1.0
-Summary: Iterate on Markdown and verify every revision with mdview.io
-License-Expression: MIT
-Project-URL: Homepage, https://mdview.io
-Project-URL: Repository, https://github.com/gogainda/mdview-cli
-Project-URL: Issues, https://github.com/gogainda/mdview-cli/issues
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click>=8.1
-Requires-Dist: httpx>=0.27
-Requires-Dist: platformdirs>=4.0
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Dynamic: license-file
-
-# mdv
-
-`mdv` opens Markdown in mdview.io and can keep an evolving file attached to one
-stable document while checking every revision in the PDF renderer.
-
-## Quick start — no token required
-
-```bash
-uv tool install mdview-cli
-mdv architecture.md
-```
-
-`mdv FILE.md` is shorthand for `mdv preview FILE.md`: it publishes the file
-anonymously and opens a temporary mdview page you can share (30-day expiry,
-2 MB limit). No account, token, or configuration required.
-
-`open` renders a local file in the browser without uploading anything at all:
-
-```bash
-mdv open architecture.md
-```
-
-## Verify every revision
-
-Saved-document commands require a mdview.io CLI token because they update your
-documents between runs. Configure it once, then sync the same file after every
-edit:
-
-```bash
-mdv keys set
-mdv sync architecture.md
-```
-
-Edit the file and run `mdv sync architecture.md` again. The share URL stays the
-same. Exit status `0` means every Mermaid diagram rendered; status `1` means the
-document needs attention.
-
-```bash
-mdv fix architecture.md
-mdv export architecture.md
-```
-
-`open` and `preview` are token-free. `sync`, `verify`, `fix`, `export`, and `list` use a token
-to access Saved documents. In CI, set `MDVIEW_TOKEN` instead of storing it.
-`MDVIEW_BASE_URL` overrides the service URL for development.

mdview_cli-0.1.0/README.md

@@ -1,45 +0,0 @@
-# mdv
-
-`mdv` opens Markdown in mdview.io and can keep an evolving file attached to one
-stable document while checking every revision in the PDF renderer.
-
-## Quick start — no token required
-
-```bash
-uv tool install mdview-cli
-mdv architecture.md
-```
-
-`mdv FILE.md` is shorthand for `mdv preview FILE.md`: it publishes the file
-anonymously and opens a temporary mdview page you can share (30-day expiry,
-2 MB limit). No account, token, or configuration required.
-
-`open` renders a local file in the browser without uploading anything at all:
-
-```bash
-mdv open architecture.md
-```
-
-## Verify every revision
-
-Saved-document commands require a mdview.io CLI token because they update your
-documents between runs. Configure it once, then sync the same file after every
-edit:
-
-```bash
-mdv keys set
-mdv sync architecture.md
-```
-
-Edit the file and run `mdv sync architecture.md` again. The share URL stays the
-same. Exit status `0` means every Mermaid diagram rendered; status `1` means the
-document needs attention.
-
-```bash
-mdv fix architecture.md
-mdv export architecture.md
-```
-
-`open` and `preview` are token-free. `sync`, `verify`, `fix`, `export`, and `list` use a token
-to access Saved documents. In CI, set `MDVIEW_TOKEN` instead of storing it.
-`MDVIEW_BASE_URL` overrides the service URL for development.

mdview_cli-0.1.0/src/mdview_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"

mdview_cli-0.1.0/src/mdview_cli.egg-info/PKG-INFO

@@ -1,63 +0,0 @@
-Metadata-Version: 2.4
-Name: mdview-cli
-Version: 0.1.0
-Summary: Iterate on Markdown and verify every revision with mdview.io
-License-Expression: MIT
-Project-URL: Homepage, https://mdview.io
-Project-URL: Repository, https://github.com/gogainda/mdview-cli
-Project-URL: Issues, https://github.com/gogainda/mdview-cli/issues
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click>=8.1
-Requires-Dist: httpx>=0.27
-Requires-Dist: platformdirs>=4.0
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Dynamic: license-file
-
-# mdv
-
-`mdv` opens Markdown in mdview.io and can keep an evolving file attached to one
-stable document while checking every revision in the PDF renderer.
-
-## Quick start — no token required
-
-```bash
-uv tool install mdview-cli
-mdv architecture.md
-```
-
-`mdv FILE.md` is shorthand for `mdv preview FILE.md`: it publishes the file
-anonymously and opens a temporary mdview page you can share (30-day expiry,
-2 MB limit). No account, token, or configuration required.
-
-`open` renders a local file in the browser without uploading anything at all:
-
-```bash
-mdv open architecture.md
-```
-
-## Verify every revision
-
-Saved-document commands require a mdview.io CLI token because they update your
-documents between runs. Configure it once, then sync the same file after every
-edit:
-
-```bash
-mdv keys set
-mdv sync architecture.md
-```
-
-Edit the file and run `mdv sync architecture.md` again. The share URL stays the
-same. Exit status `0` means every Mermaid diagram rendered; status `1` means the
-document needs attention.
-
-```bash
-mdv fix architecture.md
-mdv export architecture.md
-```
-
-`open` and `preview` are token-free. `sync`, `verify`, `fix`, `export`, and `list` use a token
-to access Saved documents. In CI, set `MDVIEW_TOKEN` instead of storing it.
-`MDVIEW_BASE_URL` overrides the service URL for development.