Synopsis
chameleon journal <subcommand> [flags]
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
Global Flags
Output format: table or jsonchameleon journal last --format=json
journal last
Show the most recent journal entries.
Synopsis
chameleon journal last [n]
Arguments
Number of entries to show
Flags
Number of entries to show (alternative to positional arg)
Examples
Last 10 Entries (Default)
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
chameleon journal last 5 --format=json
[
{
"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
Examples
No Errors
Output:
Errors Found
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...
chameleon journal errors --format=json
[
{
"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
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
ℹ No migration entries found
chameleon journal migrations --format=json
[
{
"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
Specific version to view details for (e.g., v001, v002)If omitted, shows all versions.
Examples
All Versions
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
📋 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
Output:
❌ No vault found
Run 'chameleon migrate' to initialize
Version Not Found
chameleon journal schema v999
Journal File Structure
Location
.chameleon/journal/
├── 2026-03-01.log
├── 2026-03-02.log
└── 2026-03-03.log # Today's log
{
"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
# 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
Cannot Read Journal
❌ failed to read journal: permission denied
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
See Also