buildlog

📝 Document your build journey. Share your process.

buildlog is a CLI tool for creating, validating, exporting, and uploading .buildlog files — structured logs that capture your development journey.

Installation

# Install globally
npm install -g buildlog

# Or use directly with npx
npx buildlog <command>

Quick Start

# Create a new buildlog
buildlog init

# Validate your buildlog
buildlog validate my-project.buildlog

# View statistics
buildlog info my-project.buildlog

# Export to markdown
buildlog export my-project.buildlog

# Play back in terminal
buildlog play my-project.buildlog

# Upload to buildlog.ai
buildlog auth
buildlog upload my-project.buildlog

Commands

buildlog init

Create a new buildlog file interactively.

# Interactive mode
buildlog init

# Quick mode with defaults
buildlog init -y

# Specify output path
buildlog init -o ./logs/project.buildlog

Options:

• -y, --yes — Use defaults without prompting
• -o, --output <path> — Output file path

buildlog validate <file>

Validate a buildlog file against the schema.

# Basic validation
buildlog validate my-project.buildlog

# Quiet mode (errors only)
buildlog validate my-project.buildlog -q

# Strict mode (warnings are errors)
buildlog validate my-project.buildlog -s

Options:

• -q, --quiet — Only output errors
• -s, --strict — Treat warnings as errors

buildlog info <file>

Display statistics and information about a buildlog.

# Show overview
buildlog info my-project.buildlog

# Include session details
buildlog info my-project.buildlog -s

# Include all entries
buildlog info my-project.buildlog -e

# Output as JSON
buildlog info my-project.buildlog -j

Options:

• -j, --json — Output as JSON
• -s, --sessions — Show session details
• -e, --entries — Show entry details

buildlog export <file>

Export buildlog to markdown, HTML, or JSON.

# Export to Markdown (default)
buildlog export my-project.buildlog

# Export to HTML
buildlog export my-project.buildlog -f html

# Export with dark theme
buildlog export my-project.buildlog -f html -t dark

# Custom output path
buildlog export my-project.buildlog -o ./docs/journey.md

Options:

• -f, --format <format> — Output format: markdown, html, json (default: markdown)
• -o, --output <path> — Output file path
• -t, --theme <theme> — Theme for HTML: light, dark (default: light)

buildlog play <file>

Play back buildlog entries in the terminal with a typewriter effect.

# Play at normal speed
buildlog play my-project.buildlog

# Play faster
buildlog play my-project.buildlog -s 2

# Play specific session
buildlog play my-project.buildlog --session 2

# Disable colors
buildlog play my-project.buildlog --no-color

Options:

• -s, --speed <speed> — Playback speed multiplier (default: 1)
• --session <number> — Session number to play (default: 1)
• --no-color — Disable colors

buildlog auth

Authenticate with buildlog.ai.

# Login
buildlog auth

# Check status
buildlog auth --status

# Logout
buildlog auth --logout

Options:

• --logout — Log out and clear stored credentials
• --status — Check authentication status

buildlog upload <file>

Upload a buildlog to buildlog.ai.

# Upload as private
buildlog upload my-project.buildlog

# Upload as public
buildlog upload my-project.buildlog -p

# Override project name
buildlog upload my-project.buildlog -n "My Awesome Project"

Options:

• -p, --public — Make the buildlog publicly visible
• -n, --name <name> — Override the project name
• -d, --description <desc> — Override the description

Buildlog File Format

A .buildlog file is a structured JSON file that captures your development journey:

{
  "$schema": "https://buildlog.ai/schema/v1.json",
  "meta": {
    "version": "1.0.0",
    "createdAt": "2025-01-15T10:00:00Z",
    "updatedAt": "2025-01-15T18:30:00Z",
    "generator": "buildlog-cli"
  },
  "project": {
    "name": "my-awesome-project",
    "description": "Building something cool",
    "techStack": ["TypeScript", "React", "Node.js"]
  },
  "author": {
    "name": "Jane Developer",
    "email": "[email protected]"
  },
  "sessions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "startTime": "2025-01-15T10:00:00Z",
      "endTime": "2025-01-15T12:30:00Z",
      "title": "Initial Setup",
      "entries": [
        {
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "timestamp": "2025-01-15T10:05:00Z",
          "type": "thought",
          "title": "Project Architecture",
          "content": "Decided to use a modular architecture with separate packages for core logic and CLI.",
          "tags": ["architecture", "planning"]
        },
        {
          "id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
          "timestamp": "2025-01-15T10:15:00Z",
          "type": "terminal",
          "content": "Setting up the project",
          "terminal": [
            {
              "command": "npm init -y",
              "output": "Wrote to package.json"
            }
          ]
        },
        {
          "id": "6ba7b812-9dad-11d1-80b4-00c04fd430c8",
          "timestamp": "2025-01-15T10:30:00Z",
          "type": "code",
          "title": "Main Entry Point",
          "content": "Created the main CLI entry point",
          "code": [
            {
              "language": "typescript",
              "filename": "src/index.ts",
              "code": "#!/usr/bin/env node\nimport { program } from 'commander';\n\nprogram.parse();"
            }
          ]
        }
      ]
    }
  ]
}

Entry Types

| Type | Icon | Description | |------|------|-------------| | thought | 💭 | Ideas and thinking process | | decision | 🎯 | Key decisions made | | code | 💻 | Code written or changed | | terminal | ⌨️ | Terminal commands run | | error | ❌ | Errors encountered | | fix | 🔧 | Bug fixes | | milestone | 🏆 | Major achievements | | note | 📝 | General notes | | question | ❓ | Questions to investigate | | answer | 💡 | Answers found | | research | 🔍 | Research conducted | | debug | 🐛 | Debugging sessions | | refactor | ♻️ | Code refactoring | | test | 🧪 | Testing | | deploy | 🚀 | Deployment |

Configuration

Configuration is stored in ~/.buildlog/config.json:

{
  "defaultAuthor": {
    "name": "Your Name",
    "email": "[email protected]"
  },
  "apiEndpoint": "https://api.buildlog.ai"
}

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © buildlog.ai