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. On a fresh machine, init first runs identity onboarding — it asks whether you're new to Trellis (creates your person identity at ~/.trellis/identity.json) or already have an identity (walks you through pairing a device). Non-interactive runs create the identity automatically; pass --identity skip to stay anonymous.

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