Skip to main content

​
Install Trellis

First, install the CLI globally: 
npm install -g @mindfoldhq/trellis@latest
Then initialize in your project: 
trellis init
Trellis uses your name to create a personal workspace directory. If you don’t specify -u, it will automatically detect from git config user.name.To specify manually: trellis init -u john (replace john with your actual name).

​
Platform selection

By default, trellis init sets up for Claude Code. To include other platforms: 
# Include Cursor commands
trellis init --cursor

# Include multiple platforms
trellis init --cursor --iflow

# All available platform flags
trellis init --claude     # Claude Code (default)
trellis init --cursor     # Cursor IDE
trellis init --iflow      # iFlow CLI
trellis init --opencode   # OpenCode
trellis init --codex      # Codex (OpenAI CLI)

​
Other useful flags

trellis init -t electron-fullstack   # Use a spec template
trellis init --overwrite             # Overwrite existing specs when using template
trellis init --append                # Only add missing files from template

​
What gets created

This creates a .trellis/ directory with the default structure: 
.trellis/
├── workflow.md          # How the workflow works
├── spec/                # Your coding conventions
│   ├── frontend/
│   ├── backend/
│   └── guides/
├── workspace/           # Session journals
└── tasks/               # Task tracking
For Claude Code, it also sets up .claude/ with hooks and commands. For other platforms, it creates the corresponding config directory (.cursor/, .iflow/, .agents/, etc.).

​
Updating Trellis

When a new version is released: 
npm install -g @mindfoldhq/trellis@latest
trellis update
Useful update flags: 
trellis update --dry-run     # Preview changes without applying
trellis update --force       # Overwrite all managed files
trellis update --migrate     # Run file migrations (renames, deletes)
trellis update only touches unmodified files. Your customizations stay intact. A timestamped backup is created automatically before any changes.

​
Write your first spec

Open .trellis/spec/backend/index.md (or frontend/ if that’s your focus) and fill in the template. Here’s what a real spec looks like: 
# Backend Guidelines

## Error Handling

All API endpoints return errors in this format:

{ "error": { "code": "VALIDATION_ERROR", "message": "Email is required" } }

Use AppError class from src/lib/errors.ts. Don't throw raw Error objects.

## Database

- Table names: snake_case, plural (user_sessions, not UserSession)
- Always include created_at and updated_at timestamps
- Foreign keys: {table}\_id format
Be specific. Include file paths. Show actual code from your project. Vague guidelines don’t help.

​
Test it

Start a new Claude Code session and ask it to write some code. Check if it follows your specs. If it doesn’t, your specs probably aren’t specific enough. Add more examples.

​
What’s next

Core concepts

Learn how specs, tasks, and workspaces work together.

Write better specs

Tips for writing specs that AI actually follows.

Commands

Slash commands for common workflows.

Multi-agent

Run multiple AI agents in parallel.