Upgrading

Installed with npx? One command

The launcher resolves the newest release itself, so upgrading is just:

npx @livefolio-cloud/cli --update

That re-downloads the current build. On the next run it boots the new version automatically — your data in ~/.livefolio/data is untouched.

---

From source

1. Back up your data

database.json holds everything — folios, versions, comments, analytics:

cp database.json database.backup.$(date +%Y%m%d).json

settings.json holds your MCP master key and any custom tunnel URL:

cp settings.json settings.backup.json

There is no .env to back up unless you chose to put provider keys there.

2. Pull the latest changes

git fetch origin
git checkout main
git pull origin main

3. Read the release notes

Check the releases page for anything that affects you — database format changes are called out there.

4. Install dependencies

npm install

5. Run migrations (if the release has any)

LiveFolio migrates its flat-file database automatically on first run:

npm run dev
# watch the console for migration messages

6. Verify

# Dashboard renders
curl -s http://localhost:3001/app | head -5

# API works
curl -s http://localhost:3001/api/files

# MCP responds
curl -s -X POST http://localhost:3001/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Version Compatibility

Database Format

LiveFolio OSS stores data in database.json with a stable schema. The flat-file format is designed to be backward-compatible. Breaking changes to the database schema are rare and always documented in the release notes.

API Compatibility

The REST API and MCP tools maintain backward compatibility. Deprecated endpoints are supported for at least one major version before removal.

Node.js Version

LiveFolio requires Node.js 18+. Check your version:

node --version
# Should be v18.x.x or v20.x.x

Downgrading

If an upgrade causes issues:

1. Restore the backup:

   cp database.backup.YYYYMMDD.json database.json
   

2. Checkout the previous version:

   git checkout <previous-version-tag>
   

3. Reinstall dependencies:

   npm install
   

4. Restart the server.

Troubleshooting Upgrades

"Module not found" after upgrade

rm -rf node_modules .next
npm install
npm run dev

Database won't load

Check database.json is valid JSON:

cat database.json | python3 -m json.tool > /dev/null && echo "Valid" || echo "Corrupted"

Build errors

rm -rf .next
npm run build

Check for TypeScript errors:

npx tsc --noEmit

Port already in use

lsof -ti:3000 | xargs kill
npm run dev

Staying Current

• Watch the GitHub repository for new releases
• Read the changelog before upgrading
• Test on a copy if you have production folios — copy database.json to a test directory and upgrade there first
• Join the community for upgrade announcements and migration guides