Installation

How to install Trellis globally or as a project dependency.

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:

SubpathUse
trellisFull platform engine, including TrellisVcsEngine.
trellis/cmsTrellisDB collections through createCmsClient.
trellis/coreEAV store, kernel, facts, and query primitives.
trellis/vcsVersion control types and helpers.
trellis/serverServer runtime entry points.
trellis/clientNetwork client for Trellis server instances.
trellis/reactReact provider and hooks.
trellis/aiEmbeddings and intelligence utilities.
trellis/linksFile reference parsing and resolution.
trellis/decisionsDecision 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).

FeaturePackageInstall when you need it
trellis codeopencode-ainpm i -g opencode-ai
trellis studioturtlecodenpm i -g turtlecode
Semantic search@huggingface/transformersnpm 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