cartulary

The knowledge layer of your project — decisions, issues, docs, all in one place.

⚠️ Status: Alpha — cartulary is under active development. The CLI surface and cartulary.toml schema may change in incompatible ways before 1.0. Pin a specific version (--version "0.1.0-alpha.1") and watch CHANGELOG.md before upgrading.

cartulary is a CLI tool to manage everything that gives context to your project: Architecture Decision Records (ADR), Design Decision Records (DDR), issues, and project documentation. Everything lives as plain Markdown in your repository.

📚 Documentation

Concepts — the domain vocabulary, one page per concept: docs/pages/concepts/. Same content offline via cartu man <name>.
CLI reference — every subcommand and flag: docs/pages/reference/cli/.
Configuration — the cartulary.toml schema: docs/pages/reference/config/.
Workflows — built-in status presets and the decision-record lifecycle: docs/pages/reference/workflows/.

You can also find all the documentation pages online at this address: crazy-crafters.gitlab.io/cartulary

🚀 Installation

Pre-built binary (recommended)

Download the archive for your platform from the GitLab Releases page. One-liner for Linux x86_64:

VERSION="0.1.0-alpha.1"
TARGET="x86_64-unknown-linux-gnu"
curl -fsSL "https://gitlab.com/crazy-crafters/cartulary/-/releases/v${VERSION}/downloads/cartu-${VERSION}-${TARGET}.tar.gz" \
    | tar -xz -C /tmp
mv /tmp/cartu ~/.local/bin/cartu

Available targets: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-gnu. macOS users compile from source via cargo install (next section). Verify the archive against the SHA256SUMS file attached to the same release.

For Windows: download cartu-{version}-x86_64-pc-windows-gnu.zip, unzip, place cartu.exe on your PATH.

Via `cargo binstall` (no compilation)

If you have cargo-binstall:

cargo binstall cartulary --version "0.1.0-alpha.1"

cartulary ships a [package.metadata.binstall] block pointing at the GitLab Release artefacts — binstall picks the right archive for your platform.

Via `cargo install` (compile from source)

cargo install cartulary --version "0.1.0-alpha.1"

Compiles from the published crate on crates.io. Requires Rust 1.88+ via rustup.rs.

Build from source (contributors)

git clone https://gitlab.com/crazy-crafters/cartulary
cd cartulary
cargo install --path .

Requires Rust 1.88+. Beyond rustc/cargo, the dev workflow expects just (recipe runner) and cargo-llvm-cov (coverage). Nix users get them automatically via the flake (nix develop); other contributors should install them manually:

cargo install --locked just cargo-llvm-cov
rustup component add llvm-tools-preview

⚡ 30-second tour

cartu init                                          # scaffold cartulary.toml + docs/
cartu adr new "Use PostgreSQL as primary database"  # record an architecture decision
cartu issue new --tag flow:feature "Add MFA"        # open an issue
cartu issue list
cartu check                                         # validate frontmatter, links, transitions
cartu man                                           # browse concept docs
cartu site build --out site                         # static HTML site with syntax-highlighted code

Pick the next thread from the documentation section above.

🔎 Similar tools

Tool	Category	Decision records	Issue tracking	Flow metrics	Plain files	Single binary
adr-tools	ADR CLI	✅	❌	❌	✅	❌
log4brains	ADR + web UI	✅	❌	❌	✅	❌
git-bug	Issue tracker	❌	✅	❌	❌	✅
git-issue	Issue tracker	❌	✅	❌	✅	❌
cartulary	ADR + issues	✅	✅	✅	✅	✅

The market is split: ADR tools have no issue tracking, issue trackers have no decision records. cartulary covers both, plus flow metrics, structural validation, and a ULID-based identifier scheme that survives parallel branches. See market-benchmark.md for the full analysis.

🤝 Contributing

Contributions welcome — open an issue or submit a merge request.

cartulary enforces Conventional Commits 1.0.0 (rationale in ADR-0019). Allowed types: feat, fix, docs, refactor, perf, test, build, ci, chore, style. Subject in imperative mood, lowercase, no trailing period, ≤72 chars. CI rejects non-conforming commits; to get the same check locally:

cargo install committed
just install-hooks

Releases are cut by maintainers with cargo release --execute X.Y.Z, which runs git-cliff to update CHANGELOG.md and triggers cargo publish + GitLab Release artefacts on tag push. Maintainers either enter the Nix dev shell (nix develop, which ships cargo-release and git-cliff) or install the two tools manually:

cargo install --locked cargo-release git-cliff

📄 License

CeCILL

🎨 Credits

Logo: Book cover by Lorc, from game-icons.net, licensed under CC BY 3.0.

cartulary 0.3.0-alpha.1