Skip to content

quickstart.mdx

Latest commit

 

History

History
146 lines (99 loc) · 3.67 KB

quickstart.mdx

File metadata and controls

146 lines (99 loc) · 3.67 KB
title Quickstart
description Set up Trellis in your project

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:

```markdown Backend spec example # 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
</CodeGroup>

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

<CardGroup cols={2}>

<Card title="Core concepts" icon="book" href="/concepts/overview">
  Learn how specs, tasks, and workspaces work together.
</Card>

<Card title="Write better specs" icon="pencil" href="/guides/specs">
  Tips for writing specs that AI actually follows.
</Card>

<Card title="Commands" icon="terminal" href="/guides/commands">
  Slash commands for common workflows.
</Card>

<Card title="Multi-agent" icon="users" href="/guides/multi-agent">
  Run multiple AI agents in parallel.
</Card>

</CardGroup>