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
- Learn about branches and milestones
- Explore the Idea Garden
- Set up issue tracking
- Build with the Trellis CMS SDK
- Browse the full CLI reference