---
title: "Project Setup"
description: "Create and configure your first TraceRTM project"
---

# Project Setup

This guide walks you through creating your first TraceRTM project, from initialization to configuration.

## Initialize a New Project

### Using the CLI

```bash
# Create a new project in the current directory
tracertm init

# Or create in a specific directory
tracertm init my-project

# Initialize with a template
tracertm init --template software-development
```

### Interactive Setup

When you run `tracertm init`, you'll be prompted for:

```
? Project name: my-web-app
? Description: E-commerce platform with user authentication
? Default view: FEATURE
? Storage backend: local (markdown files)
? Enable agent support: yes
```

## Project Structure

After initialization, your project has this structure:

```
my-project/
├── .tracertm/
│   ├── config.yaml      # Project configuration
│   ├── workflows.yaml   # State machine definitions
│   └── permissions.yaml # Access control (optional)
├── artifacts/
│   ├── features/        # Feature artifacts
│   ├── tests/           # Test artifacts
│   ├── code/            # Code artifacts
│   └── ...              # Other artifact types
└── README.md
```

## Configuration File

The main configuration file `.tracertm/config.yaml`:

```yaml
# .tracertm/config.yaml
project:
  name: my-web-app
  description: E-commerce platform with user authentication
  version: "1.0"

storage:
  backend: local  # local, sqlite, postgresql
  path: ./artifacts

defaults:
  view: FEATURE
  status: draft
  id_prefix:
    feature: FEAT
    test: TEST
    code: CODE
    api: API

views:
  enabled:
    - FEATURE
    - CODE
    - TEST
    - API
    - WIREFRAME
    - DATABASE

agents:
  enabled: true
  allow_auto_linking: true
```

## Storage Backends

### Local Storage (Default)

Best for: Git-based workflows, small to medium projects

```yaml
storage:
  backend: local
  path: ./artifacts
  format: markdown  # markdown or yaml
```

Artifacts are stored as Markdown files:

```markdown
<!-- artifacts/features/FEAT-001.md -->
---
id: FEAT-001
title: User Authentication
type: feature
status: in_progress
owner: alice@example.com
priority: high
---

# User Authentication

Implement secure user login with OAuth2 support.

## Acceptance Criteria

- [ ] Users can log in with email/password
- [ ] OAuth2 with Google and GitHub
- [ ] Session management with JWT
- [ ] Password reset flow
```

### SQLite Storage

Best for: Single-user, portable databases

```yaml
storage:
  backend: sqlite
  path: ./tracertm.db
```

### PostgreSQL Storage

Best for: Team collaboration, production deployments

```yaml
storage:
  backend: postgresql
  connection:
    host: localhost
    port: 5432
    database: tracertm
    user: tracertm_user
    password: ${TRACERTM_DB_PASSWORD}  # Environment variable
```

## Project Templates

TraceRTM includes templates for common use cases:

| Template | Description | Views Enabled |
|----------|-------------|---------------|
| `minimal` | Bare minimum setup | FEATURE, TEST |
| `software-development` | Full software project | All 16 views |
| `api-project` | API-focused development | FEATURE, API, TEST, CODE |
| `data-pipeline` | Data engineering | DATA_FLOW, DATABASE, MONITORING |

```bash
# List available templates
tracertm templates list

# Use a template
tracertm init --template api-project
```

## Verify Setup

After initialization, verify your project:

```bash
# Check project status
tracertm status

# Output:
# Project: my-web-app
# Storage: local (./artifacts)
# Artifacts: 0
# Views enabled: 6
# Agent support: enabled
```

## Connect to Remote Server

For team collaboration, connect to a TraceRTM server:

```bash
# Configure remote server
tracertm config set server.url https://tracertm.example.com
tracertm config set server.api_key ${TRACERTM_API_KEY}

# Verify connection
tracertm server ping
```

## Environment Variables

TraceRTM respects these environment variables:

| Variable | Description |
|----------|-------------|
| `TRACERTM_PROJECT` | Default project path |
| `TRACERTM_CONFIG` | Custom config file path |
| `TRACERTM_API_KEY` | API key for remote server |
| `TRACERTM_DB_PASSWORD` | Database password |
| `TRACERTM_LOG_LEVEL` | Logging verbosity (debug, info, warn) |

## Next Steps

Your project is ready. Continue with:

- [Creating Requirements](/docs/getting-started/first-project/requirements) - Add your first features
- [Creating Test Cases](/docs/getting-started/first-project/test-cases) - Define tests
- [Establishing Traceability](/docs/getting-started/first-project/traceability) - Link artifacts

