Commons is the shared public library for Vimaksh. You write a file; Commons adds a page, an entry in the library, and searchable text. You keep the original file and its attachments in Git.
Install once
You need Python 3.11 or newer, Git, and access to the private repository. Authenticate Git with your normal GitHub credentials. If you use GitHub CLI:
gh auth login
gh auth setup-git
Install the CLI with uv:
uv tool install git+https://github.com/prag-man/commons.git
commons init
cd commons
If you have already cloned the repository, run commands there instead of
commons init. For development, use uv sync --frozen and prefix commands
with uv run --frozen.
Add a file
commons add ~/notes/decision.md --owner Platform --tag decisions
commons add ~/reports/experiment.html --owner Research --tag experiments
No front matter is required. Commons infers a title from the first Markdown
heading or the HTML title, and creates a summary from readable text. Set
--title, --summary, and --slug when you want to choose them explicitly.
commons add ~/notes/decision.md \
--title "How we publish documents" \
--slug publishing-decision \
--summary "The choices behind the shared library." \
--owner Platform --tag decisions
Each document gets a stable address:
https://commons.vimaksh.in/d/publishing-decision/
commons add only imports the file into your local checkout. It does not
commit, push, or publish anything.
Preview and publish
commons preview
Open the printed 127.0.0.1 URL. Check the document and try finding it with
search. Press Ctrl+C when finished. Use --port 8766 if the default port is
already in use.
commons publish
This validates and builds the library, commits changes under documents/, and
pushes to main. Connected hosting rebuilds after that push. The CLI reports pushed,
which means Git accepted the changes; it does not claim that deployment has
finished. A successful hosting build makes the new page live.
Initial rollout, 22 October 2026: the public library is live. Automatic deployment is pending the Cloudflare Pages GitHub app's access to the private repository. Until that connection is enabled, publishing updates Git and an administrator must deploy the built site separately. Check the repository README for the current hosting status.
The command refuses an already staged Git index, a different branch, a checkout behind the remote, changes to tracked non-document files, or local commits that include unrelated code. It never force-pushes, auto-merges, or commits your application code. For a review workflow, commit your document on a feature branch and open a normal pull request instead.
Update the same link
commons add ~/notes/decision.md --slug publishing-decision --replace
commons preview
commons publish --message "Update the publishing decision"
The slug and creation date stay stable. Attachments already in the bundle
are kept unless explicitly replaced. The imported file is a copy: edit your
original and re-import it, or edit the file under documents/ directly.
Images and attachments
Keep local assets next to the source file, or in a directory beside it:
my-report/
report.html
images/chart.png
styles/report.css
Direct image, script, and stylesheet references are imported automatically,
including CSS url() resources. File paths must stay inside the source
folder. Root-relative URLs refer to the hosted site, so use relative paths
for assets. Runtime-generated requests and module import graphs are not
automatically discovered; include their directories explicitly:
commons add ./report.html --assets ./assets --assets ./results.csv
Self-contained HTML reports work directly. HTML keeps its CSS and scripts and is displayed in a sandboxed reader. The sandbox permits scripts, downloads, and popups, but does not grant same-origin access to the library. HTML that depends on same-origin fetch or module loading may need to be made self-contained. The original file remains downloadable.
Metadata in Markdown
Optional YAML front matter is read when importing:
---
title: A useful decision
summary: The context and tradeoffs behind the decision.
owner: Platform
tags:
- decisions
- architecture
---
The generated document.json is the authoritative metadata after import.
Explicit CLI flags override front matter. Do not rename an established slug
to change its title.
List and search from the terminal
commons list
commons search "source maps"
commons --library ~/commons add ./another-note.md
Search matches all query words across the title, summary, owner, tags, and readable body. HTML scripts and styles are excluded; text inside inactive report tabs is included. Search is basic word-prefix matching, not semantic search. The browser fetches one static index and searches locally.
Drafts and visibility
commons add ./draft.md --draft
commons preview --include-drafts
Drafts are omitted from the public build, catalog, and search index. The repository is private, but every published document and its included attachments can be read by anyone. Draft status is a publishing state rather than an access-control system. Publish only material intended for that audience.
For the exact file layout and metadata rules, read the publishing protocol.