Quick Start

Initialize a Repository

cd my-project
trellis init

This creates a .trellis/ directory, scans your filesystem, and generates an initial op for every tracked file.

Start Watching

trellis watch

Trellis watches your filesystem in real time. Every file save creates an immutable op — no staging, no committing.

Check Status

trellis status

Shows your current branch, op count, tracked files, and recent operations.

Create a Milestone

When you reach a meaningful point — feature done, bug fixed, refactor complete:

trellis milestone create -m "Implement user authentication"

Milestones span a range of ops and carry a narrative message. They're your curated history.

View History

trellis log --limit 20

Shows the causal op stream with content-addressed hashes and timestamps.

Import from Git

Already have a Git repository? Import its history:

trellis import --from /path/to/git-repo

Git commits become Trellis milestones, preserving your existing history.

Programmatic Usage

import { TrellisVcsEngine } from "trellis";

const engine = new TrellisVcsEngine({ rootPath: "/my/project" });
await engine.initRepo();
engine.open();

// Check status
const status = engine.status();
console.log(status);

// Create a milestone
await engine.createMilestone("Initial setup");

// View history
const history = engine.log();
console.log(history);

Read Content Collections

Use trellis/cms when you want a website or app to consume schema-aware TrellisDB collections:

import { createCmsClient } from "trellis/cms";

const cms = createCmsClient({
  url: "http://localhost:4096",
  directory: "/absolute/path/to/my-project",
});

const posts = await cms.collection("blog_post").list({
  status: "published",
  expand: ["author"],
});

Collection entries include normal fields, references, images, and virtual formula fields computed from the schema.

Next Steps

• Learn about branches and milestones
• Explore the Idea Garden
• Set up issue tracking
• Build with the Trellis CMS SDK
• Browse the full CLI reference