better-age

better-age is a simple cli for local-first workflow for encrypted .env files sharing.

It keeps the team habit simple: one env file, few teammate, one local command. The file you pass around is age-encrypted ciphertext, and access changes are explicit payload rewrites.

Quickstart

Install the CLI globally:

npm install -g @better-age/cli

Create and edit one encrypted payload:

bage setup --name Alice
bage create .env.enc
bage edit .env.enc
bage view .env.enc

Share with Bob:

bage identity import 'better-age://identity/v1/...' --alias bob
bage grant .env.enc bob

Load for machines:

bage load .env.enc --protocol-version=1

Or use the varlock plugin:

# .env.schema

# @plugin(@better-age/varlock)
# @initBetterAge(path=.env.enc)
# @setValuesBulk(betterAgeLoad(), format=env)

varlock run -- npm run dev

Full docs:

• Install
• Quickstart
• Share with a teammate
• CLI reference
• Varlock plugin reference

What It Is

• age is the cryptographic primitive.
• better-age is the local UX layer around env payloads, identities, grants, revokes, and machine loading.
• Payloads are visible caller-owned files, not hidden cloud state.
• Humans use bage view; machines use bage load --protocol-version=1.
• Scope stays narrow: env-file workflow, not general-purpose secret management.

Packages

Path	Package	Job
packages/cli	@better-age/cli	Release-facing bage CLI. Owns terminal UX, command flows, prompts, editor/viewer adapters, and stdout/stderr policy.
packages/core	@better-age/core	Internal core library for artifact codecs, identity lifecycle, payload lifecycle, migrations, crypto ports, and typed outcomes.
packages/varlock	@better-age/varlock	Thin Varlock plugin. Shells out to bage load --protocol-version=1 <path> and preserves the stdio contract.
packages/cli-legacy	private	Old proof-of-concept reference. Not a release target.

Monorepo Map

• apps/website: docs website source for https://bage.paulsenon.com/docs
• infra/website: Alchemy/Cloudflare deployment for the docs website
• docs: release operations, manual QA, ADRs, and maintenance docs
• VISION.md: product bet and tradeoffs
• UBIQUITOUS_LANGUAGE.md: canonical project terms
• CONTRIBUTING.md: repo rules, reading order, and checks
• LICENSE: project license
• THIRD_PARTY_NOTICES.md: dependency notices

Repo Setup

Requirements:

• Node.js
• pnpm

Install workspace dependencies:

pnpm install

Useful checks:

pnpm check
pnpm test

Per package:

pnpm -F @better-age/cli check
pnpm -F @better-age/core test
pnpm -F @better-age/varlock check

Contributing Index

Start here:

• CONTRIBUTING.md: repo contribution guide
• .github/PULL_REQUEST_TEMPLATE.md: PR checklist
• docs/manual-qa.md: manual behavior checklist
• docs/release-operations.md: release flow
• docs/contributor-schema-breaking-changes.md: schema migration notes
• docs/adr: architecture decisions

Docs split:

• root README: project pitch, quickstart, package index, contribution index
• package README: package contract, install/build shape, package-specific usage
• website docs: user-facing tutorials and reference