Short for Bowerbird, pronounced "birb."
The type system for your notes. Bowerbird is a CLI that creates, validates, queries, and migrates Markdown notes against a schema. Your files remain plain Markdown; Bowerbird supplies the guardrails.
It is especially useful beneath AI agents that write to a vault: the agent can work quickly while deterministic commands enforce structure, find notes, and catch drift. Bowerbird does not call an LLM or require an account, cloud, or database.
Warning
Bowerbird is pre-release software. The CLI is usable, but its schema format and command surface may change before v1.0. Follow the roadmap for current direction.
- Schema enforcement for Markdown. Define types, inherited fields, relations, templates, and body structure without surrendering your files to an app.
- Safe evolution. Audit existing notes, preview repairs, and migrate schemas explicitly as your vault changes.
- One deterministic CLI. Create, edit, find, open, and batch-update notes interactively or through machine-readable automation.
Bowerbird is not a note editor, sync service, database, CMS, or version-control system. Use the tools you already like for those jobs; Bowerbird keeps the notes they touch structurally sound.
Bowerbird requires Node.js 22 or newer.
npm install -g bwrb
bwrb --versionOr install it with pnpm:
pnpm add -g bwrbSee the full installation guide for shell completion, upgrades, and troubleshooting.
mkdir my-vault
cd my-vault
bwrb init --yes
bwrb --vault . --non-interactive schema new type idea --directory Ideas --output json
bwrb --vault . --non-interactive new idea --json '{"name":"First idea"}'
bwrb --vault . list --type idea --output jsonThis creates .bwrb/schema.json, adds an idea type, writes Ideas/First idea.md, and lists the result as JSON. The schema is the source of truth for the vault's types and fields.
Continue with the five-minute Quick Start to define prompted fields and audit your first notes.
Once a vault has a schema, everyday commands look like this:
bwrb new idea
bwrb list --type idea
bwrb edit "My Idea"
bwrb auditRun bwrb --help or <command> --help to inspect the installed command surface. Use --vault /path/to/vault from outside a vault, or let Bowerbird discover the nearest .bwrb/schema.json from your current directory.
| Goal | Commands | Documentation |
|---|---|---|
| Create and edit typed notes | new, edit, delete |
Creating notes |
| Find, inspect, and open notes | list, recent |
Finding notes |
| Define and evolve types | schema |
Schema reference |
| Detect and repair drift | audit, bulk |
Auditing |
| Reuse note structures | template |
Templates |
| Preserve document ancestry | lineage, new --fork |
Lineage |
| Save repeatable queries | dashboard |
Dashboards |
| Configure and automate vaults | config, --non-interactive, JSON modes |
JSON automation |
The complete user documentation lives at bwrb.dev. User-facing CLI behavior is canonical there; product rationale and plans live in docs/product.
Each vault contains a version 2 schema at .bwrb/schema.json. Types live in a flat map and can extend one parent type. Fields may be static, prompted, derived from vault relations, or constrained to select options. Templates add reusable defaults, bodies, and related-note scaffolding.
Markdown remains the source of truth. Bowerbird refuses invalid writes through its CLI, while bwrb audit finds drift introduced by external editors or agents. Schema migrations make structural changes explicit and reviewable.
For the complete contracts, use the canonical guides:
- Types and inheritance
- Schema concepts
- Templates
- Schema migrations
- Targeting notes and vaults
- Getting started
Clone the repository and install the pinned pnpm version's dependencies:
git clone https://github.com/3mdistal/bwrb.git
cd bwrb
corepack enable
pnpm install
pnpm buildRun the CLI from source with pnpm dev -- <command>. Before pushing code, run the repository's CI-parity checks in this exact order:
pnpm build
pnpm verify:pack
pnpm typecheck
pnpm lint
pnpm knip
pnpm test -- --exclude='**/*.pty.test.ts'Contributor and architecture guidance lives in AGENTS.md. Documentation work should also follow the canonical documentation policy.