Quick Start

A 60-second graph smoke test, then a five-minute walkthrough of init, watch, and milestones.

Try it in 60 seconds

From an empty directory (after installing the CLI):

mkdir trellis-demo && cd trellis-demo
trellis init --no-interactive --identity skip
trellis status
trellis issue create -t "Hello graph"
trellis query 'find ?e where type = "Issue"'
trellis examples

Quote the whole query string. Issues use type = "Issue" in TQL.

See a graph UI from npm: trellis ui --legacy (bundled System Visualizer). The full Svelte explorer ships with the kernel git repo, not the npm tarball; clone the repo and run trellis ui there.

Studio or agent harness: trellis studio and trellis code are separate surfaces; see Trellis Studio.

Five-minute walkthrough

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