Prerequisites
- Bun ≥ 1.0 (recommended) or Node.js ≥ 20
- No other native dependencies
Global Install
Install Trellis globally to use the CLI anywhere:
npm install -g trellis
trellis -h
Or use npx without installing:
npx trellis -h
Project Dependency
Add Trellis to your project:
npm install trellis
Then import the engine programmatically:
import { TrellisVcsEngine } from "trellis";
const engine = new TrellisVcsEngine({ rootPath: "/my/project" });
await engine.initRepo();
Subpath Imports
Trellis exposes modular subpaths so you can depend on only what you need:
| Subpath | Use |
|---|---|
trellis | Full platform engine, including TrellisVcsEngine. |
trellis/cms | TrellisDB collections through createCmsClient. |
trellis/core | EAV store, kernel, facts, and query primitives. |
trellis/vcs | Version control types and helpers. |
trellis/server | Server runtime entry points. |
trellis/client | Network client for Trellis server instances. |
trellis/react | React provider and hooks. |
trellis/ai | Embeddings and intelligence utilities. |
trellis/links | File reference parsing and resolution. |
trellis/decisions | Decision trace recording and querying. |
Optional integrations
Trellis keeps its install lean. The heavyweight agent and ML integrations are optional peer dependencies, so npm never installs them automatically (4.0.3+: a global install went from ~1.3 GB to ~85 MB on ARM64 Linux).
| Feature | Package | Install when you need it |
|---|---|---|
trellis code | opencode-ai | npm i -g opencode-ai |
trellis studio | turtlecode | npm i -g turtlecode |
| Semantic search | @huggingface/transformers | npm i -g @huggingface/transformers |
Each command tells you what to install when its package is missing, and Trellis degrades gracefully without them.
Verify Installation
trellis --version