Migration Guide

Overview

Conduct v0.2.0 introduces a new backend-powered architecture. This guide helps you migrate from v0.1.

What Changed

Architecture

• v0.1: CLI with local database (libSQL/Turso)
• v0.2: Self-hosted backend with database

Key Differences

1. Backend Required: v0.2 requires a running backend
2. Profile System: New profile-based configuration
3. API Communication: CLI talks to backend via REST API
4. No Local Database: No more _conduct/memory.db
5. Centralized Storage: Backend stores all data

Migration Options

Option A: Fresh Start (Recommended)

Start fresh with v0.2:

1. Setup backend
2. Configure CLI profile
3. Start using new workflow

Pros: Clean, simple, no compatibility issues

Cons: Lose v0.1 data (unless exported first)

Option B: Export and Import

Export v0.1 data and import to v0.2:

1. Export v0.1 data
2. Setup v0.2 backend
3. Import data to v0.2
4. Verify integrity

Pros: Keep existing data

Cons: More complex, manual process

Option C: Parallel Usage

Run both versions side by side:

1. Keep v0.1 for old projects
2. Use v0.2 for new projects
3. Use --v1 flag for old commands

Pros: Gradual migration

Cons: Manage two systems

Fresh Start Migration

Step 1: Backup v0.1 Data

Save your current data:

# Copy database
cp _conduct/memory.db _conduct/memory.db.backup
 
# Copy all files
tar -czf conduct-v01-backup.tar.gz _conduct/

Step 2: Setup v0.2 Backend

cd backend
 
# Start database
docker-compose up -d postgres
 
# Run migrations
npm run db:setup
 
# Start server
tsx example-server.ts

Save the admin API key from output.

Step 3: Install v0.2 CLI

npm install -g conduct-cli@0.2.0

Step 4: Configure Profile

conduct profile add \
  --name local \
  --url http://localhost:3000/conduct \
  --key <your-api-key> \
  --project myproject
 
conduct profile use local

Step 5: Verify Setup

conduct profile test
conduct list

Step 6: Start Fresh

cd your-project
conduct init

You're now using v0.2!

Export and Import Migration

Step 1: Export v0.1 Data

Create export script export-v01.js:

const Database = require('better-sqlite3');
const fs = require('fs');
 
const db = new Database('_conduct/memory.db');
 
const specs = db.prepare('SELECT * FROM specs').all();
const runs = db.prepare('SELECT * FROM runs').all();
const checks = db.prepare('SELECT * FROM checks').all();
const features = db.prepare('SELECT * FROM features').all();
 
const data = { specs, runs, checks, features };
 
fs.writeFileSync('conduct-v01-export.json', JSON.stringify(data, null, 2));
console.log('Export complete!');

Run export:

node export-v01.js

Step 2: Setup v0.2 Backend

Follow "Fresh Start Migration" steps 2-5.

Step 3: Import Data

Create import script import-v02.js:

const fs = require('fs');
const axios = require('axios');
 
const data = JSON.parse(fs.readFileSync('conduct-v01-export.json'));
const API_URL = 'http://localhost:3000/conduct/v1';
const API_KEY = 'sk_admin_xxx'; // Your key
 
async function importData() {
  // Import specs
  for (const spec of data.specs) {
    await axios.post(`${API_URL}/specs`, {
      specId: spec.spec_id,
      title: spec.title,
      content: spec.content,
      status: spec.status,
    }, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    });
  }
 
  // Import runs
  for (const run of data.runs) {
    await axios.post(`${API_URL}/runs`, {
      runId: run.run_id,
      specId: run.spec_id,
      content: run.content,
      status: run.status,
    }, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    });
  }
 
  // Import checks
  for (const check of data.checks) {
    await axios.post(`${API_URL}/checks`, {
      checkId: check.check_id,
      runId: check.run_id,
      content: check.content,
      result: check.result,
    }, {
      headers: { Authorization: `Bearer ${API_KEY}` }
    });
  }
 
  console.log('Import complete!');
}
 
importData().catch(console.error);

Run import:

node import-v02.js

Step 4: Verify Import

conduct spec list
conduct run list
conduct check list

Compare counts with v0.1 data.

Parallel Usage

Keep both versions installed:

Use v0.1

conduct list --v1
conduct spec create spec.md --v1

Use v0.2 (default)

conduct list
conduct spec create spec.md

Separate Projects

# Old project (v0.1)
cd old-project
conduct list --v1
 
# New project (v0.2)
cd new-project
conduct list

Configuration Changes

v0.1 Configuration

_conduct/memory.db
~/.conduct/config.json (libSQL credentials)

v0.2 Configuration

~/.conduct/credentials.json (profiles)
_conduct/ (local file cache)

Command Changes

Most commands work the same, but with new options:

Profile Commands (New in v0.2)

conduct profile add
conduct profile list
conduct profile use <name>
conduct profile test
conduct profile remove <name>

Entity Commands (Updated)

# v0.1
conduct spec create spec.md
 
# v0.2 (same, but with backend)
conduct spec create spec.md
 
# v0.2 with dry-run
conduct spec create spec.md --dry-run
 
# v0.2 with specific profile
conduct spec create spec.md --profile staging

Breaking Changes

1. No local database: Must have backend running
2. Profile required: Must configure at least one profile
3. API key required: Authentication mandatory
4. Turso removed: No direct Turso support in v0.2
5. File paths: Content stored on backend, not locally

Compatibility

Backward Compatibility

• Use --v1 flag for v0.1 commands
• Old _conduct/memory.db still works with --v1
• Can run both versions simultaneously

Forward Compatibility

• v0.1 database cannot be used directly in v0.2
• Must export and import data
• File formats compatible (markdown)

Troubleshooting

Backend Not Running

Error: Cannot connect to backend

Solution: Start backend first:

cd backend
tsx example-server.ts

Profile Not Configured

Error: No active profile

Solution: Add and activate profile:

conduct profile add --name local ...
conduct profile use local

Data Missing After Migration

Verify export and import:

# Check export file
cat conduct-v01-export.json | jq '.specs | length'
 
# Check imported data
conduct spec list --json | jq '.specs | length'

Permission Denied

API key lacks permissions. Create new key with full permissions:

# On backend
curl -X POST http://localhost:3000/conduct/v1/auth/keys \
  -H "Authorization: Bearer sk_admin_xxx" \
  -d '{"name": "migration", "permissions": ["read","write","delete"]}'

Post-Migration

Clean Up v0.1

After successful migration:

# Remove old database
rm _conduct/memory.db
 
# Remove old config
rm ~/.conduct/config.json
 
# Keep backups!

Team Onboarding

Share backend URL and API keys with team:

# Each team member runs:
conduct profile add \
  --name team \
  --url https://backend.company.com/conduct \
  --key sk_team_xxx \
  --project ourproject
 
conduct profile use team

Getting Help

• Documentation
• GitHub Issues
• Migration FAQ

FAQ

Q: Do I have to migrate? A: No, v0.1 still works with --v1 flag. Migrate when ready.

Q: Can I migrate gradually? A: Yes, use parallel usage approach.

Q: Will I lose data? A: Only if you don't export first. Always backup before migrating.

Q: Can I go back to v0.1? A: Yes, if you keep backups. Restore _conduct/memory.db.

Q: Do I need Docker? A: For backend, yes. Or use managed PostgreSQL.

Q: Can I use SQLite? A: For development only. Use PostgreSQL for production.