chameleon journal - ChameleonDB

Synopsis

chameleon journal <subcommand> [flags]

View and search the operation journal (audit log).

Description

The journal is an append-only log of all ChameleonDB operations. It provides:

Complete audit trail - Every operation is logged
Daily rotation - Stored in .chameleon/journal/ with date-based files
Never deleted - Append-only, immutable history
Multiple formats - Table or JSON output

Use the journal to:

Audit database changes
Debug migration issues
Track schema evolution
Monitor operation performance

Subcommands

journal last - Show last N operations
journal errors - Show error operations
journal migrations - Show migration history
journal schema - Show schema version history (vault)

Global Flags

string

default:"table"

Output format: table or json

chameleon journal last --format=json

journal last

Show the most recent journal entries.

Synopsis

chameleon journal last [n]

Arguments

number

default:"10"

Number of entries to show

Flags

number

default:"10"

Number of entries to show (alternative to positional arg)

Examples

Last 10 Entries (Default)

chameleon journal last

Output:

Timestamp                Action      Status      Details
─────────────────────────────────────────────────────────────────
2026-03-03 10:30:15      migrate     started     action=check dry_run=false apply=false
2026-03-03 10:30:16      migrate     no_changes  action=check
2026-03-03 14:25:30      migrate     started     action=check dry_run=false apply=true
2026-03-03 14:25:31      migrate     applied     duration=23ms
2026-03-03 15:10:00      verify      completed   

Last 20 Entries

chameleon journal last 20

JSON Format

chameleon journal last 5 --format=json

Output:

[
  {
    "timestamp": "2026-03-03T14:25:31Z",
    "action": "migrate",
    "status": "applied",
    "duration_ms": 23
  },
  {
    "timestamp": "2026-03-03T15:10:00Z",
    "action": "verify",
    "status": "completed"
  }
]

journal errors

Show error operations from today’s journal.

Synopsis

chameleon journal errors

Examples

No Errors

chameleon journal errors

Output:

✓ No errors found

Errors Found

chameleon journal errors

Output:

Timestamp                Action      Status      Details
─────────────────────────────────────────────────────────────────
2026-03-03 11:45:23      migrate     error       error=failed to connect to database: connection ref...
2026-03-03 12:30:15      migrate     error       error=failed to execute migration: ERROR: column "a...

JSON Format

chameleon journal errors --format=json

Output:

[
  {
    "timestamp": "2026-03-03T11:45:23Z",
    "action": "migrate",
    "status": "error",
    "error": "failed to connect to database: connection refused"
  }
]

journal migrations

Show migration history from the journal.

Synopsis

chameleon journal migrations

Examples

Migration History

chameleon journal migrations

Output:

Timestamp                Version              Status    Duration
─────────────────────────────────────────────────────────────────
2026-03-03 10:32:15      v001                 applied   45ms
2026-03-03 14:25:31      v002                 applied   23ms
2026-03-03 16:10:22      v003                 applied   67ms

No Migrations Yet

chameleon journal migrations

Output:

ℹ No migration entries found

JSON Format

chameleon journal migrations --format=json

Output:

[
  {
    "timestamp": "2026-03-03T10:32:15Z",
    "action": "migrate",
    "status": "applied",
    "duration_ms": 45
  },
  {
    "timestamp": "2026-03-03T14:25:31Z",
    "action": "migrate",
    "status": "applied",
    "duration_ms": 23
  }
]

journal schema

View schema version history from the Schema Vault.

Synopsis

chameleon journal schema [version]

Arguments

string

Specific version to view details for (e.g., v001, v002)If omitted, shows all versions.

Examples

All Versions

chameleon journal schema

Output:

📖 Schema Version History

v003 (current) ✓
├─ Hash: 9e2f5a1b...
├─ Date: 2026-03-03 16:10:00
├─ Author: dperalta
├─ Changes: Added Comment entity
└─ Parent: v002

v002
├─ Hash: 7d4e1c2a...
├─ Date: 2026-03-03 14:25:00
├─ Author: dperalta
├─ Changes: Added age field to User
└─ Parent: v001

v001
├─ Hash: 3f2a8b9c...
├─ Date: 2026-03-03 10:30:00
├─ Author: dperalta
├─ Changes: Initial schema
└─ Parent: none

Specific Version

chameleon journal schema v002

Output:

📋 Schema Version: v002
─────────────────────────────────────────
Hash:      7d4e1c2a3b5f6e8d9a1b2c3d4e5f6a7b
Timestamp: 2026-03-03T14:25:00Z
Author:    dperalta
Parent:    v001
Status:    locked ✓

📝 Changes Summary:
  Added age field to User

📂 Files:
  • schemas/users.cham
  • schemas/posts.cham

No Vault Found

chameleon journal schema

Output:

❌ No vault found
   Run 'chameleon migrate' to initialize

Version Not Found

chameleon journal schema v999

Output:

❌ Version v999 not found

Journal File Structure

Location

.chameleon/journal/
├── 2026-03-01.log
├── 2026-03-02.log
└── 2026-03-03.log  # Today's log

Format

Each log entry is JSON:

{
  "timestamp": "2026-03-03T14:25:31Z",
  "action": "migrate",
  "status": "applied",
  "duration": 23,
  "details": {
    "version": "v002",
    "tables_created": 0
  }
}

Daily Rotation

New file created daily
Old files never deleted (append-only)
Date format: YYYY-MM-DD.log

Common Use Cases

Debug Failed Migration

# Find all errors
chameleon journal errors

# Get last 50 entries for context
chameleon journal last 50

Audit Schema Changes

# View all schema versions
chameleon journal schema

# Check specific version
chameleon journal schema v002

Monitor Performance

# Export to JSON for analysis
chameleon journal migrations --format=json > migrations.json

Track User Activity

# View recent operations
chameleon journal last 100

Integration Examples

Export to CSV

#!/bin/bash
# Export migration history to CSV

chameleon journal migrations --format=json | \
  jq -r '.[] | [.timestamp, .action, .status, .duration_ms] | @csv' > migrations.csv

Alert on Errors

#!/bin/bash
# Check for errors in last hour

ERRORS=$(chameleon journal errors --format=json | jq length)

if [ "$ERRORS" -gt 0 ]; then
  echo "⚠️  $ERRORS errors detected in journal"
  chameleon journal errors
  exit 1
fi

Daily Report

#!/bin/bash
# Generate daily migration report

echo "ChameleonDB Daily Report - $(date)"
echo ""
echo "Migrations today:"
chameleon journal migrations
echo ""
echo "Errors today:"
chameleon journal errors

Troubleshooting

No Journal Entries

ℹ No journal entries found

Reason: No operations have been performed yet. Solution: Run a migration or other command:

chameleon migrate

Cannot Read Journal

❌ failed to read journal: permission denied

Solution: Ensure permissions:

chmod -R u+r .chameleon/journal/

Journal File Corrupted

If a journal file is corrupted (invalid JSON), the command may fail. Recovery:

Identify corrupted file:
jq . .chameleon/journal/2026-03-03.log

Move to backup:

mv .chameleon/journal/2026-03-03.log .chameleon/journal/2026-03-03.log.backup

Create empty file:

touch .chameleon/journal/2026-03-03.log

​Synopsis

​Description

​Subcommands

​Global Flags

​journal last

​Synopsis

​Arguments

​Flags

​Examples

​Last 10 Entries (Default)

​Last 20 Entries

​JSON Format

​journal errors

​Synopsis

​Examples

​No Errors

​Errors Found

​JSON Format

​journal migrations

​Synopsis

​Examples

​Migration History

​No Migrations Yet

​JSON Format

​journal schema

​Synopsis

​Arguments

​Examples

​All Versions

​Specific Version

​No Vault Found

​Version Not Found

​Journal File Structure

​Location

​Format

​Daily Rotation

​Common Use Cases

​Debug Failed Migration

​Audit Schema Changes

​Monitor Performance

​Track User Activity

​Integration Examples

​Export to CSV

​Alert on Errors

​Daily Report

​Troubleshooting

​No Journal Entries

​Cannot Read Journal

​Journal File Corrupted

​See Also

Synopsis

Description

Subcommands

Global Flags

journal last

Synopsis

Arguments

Flags

Examples

Last 10 Entries (Default)

Last 20 Entries

JSON Format

journal errors

Synopsis

Examples

No Errors

Errors Found

JSON Format

journal migrations

Synopsis

Examples

Migration History

No Migrations Yet

JSON Format

journal schema

Synopsis

Arguments

Examples

All Versions

Specific Version

No Vault Found

Version Not Found

Journal File Structure

Location

Format

Daily Rotation

Common Use Cases

Debug Failed Migration

Audit Schema Changes

Monitor Performance

Track User Activity

Integration Examples

Export to CSV

Alert on Errors

Daily Report

Troubleshooting

No Journal Entries

Cannot Read Journal

Journal File Corrupted

See Also