@tryhuset/foundation-utils

Public utility CLI tools for Foundation server framework. Provides generic tools for database and Docker management that can be installed without GitHub Personal Access Tokens.

Installation

npm install -g @tryhuset/foundation-utils

Usage

Database management

foundation-utils db list      # List sessions
foundation-utils db restore   # Restore a session by ID (ends current active if any)
foundation-utils db export    # Export database to mongodump backup
foundation-utils db import    # Import database from mongodump backup
foundation-utils db end       # End all active sessions

Requires STORAGE_URL environment variable. Use -e, --env <path> to load from a .env file.

db list – List sessions (default 50, newest first). Use -a, --active for active only, -l, --limit <n> to change limit.

db restore – Restore a session by ID. Ends the current active session if one exists. Requires -i, --id <sessionId>. Restart the server to pick up the restored session.

db export – Create mongodump backup. Requires -o, --out <path> for output directory.

db import – Import from mongodump backup. Requires -p, --path <path> to dump directory.

db end – Ends all sessions by updating endedAt with null to have the current date.

Docker Compose management

Uses ./compose.yaml by default. Override with -f, --file <path>.

# Update images with backup (default: ./compose.yaml)
foundation-utils docker update

# Create backup only
foundation-utils docker backup

# Restore stack from a backup compose file (from docker backup output)
foundation-utils docker backup --restore ./docker_image_backups/docker-compose_20260101T120000.yaml

# Update without backup
foundation-utils docker update --no-backup

# Force without confirmation (e.g. restore)
foundation-utils docker backup --restore ./docker_image_backups/docker-compose_20260101T120000.yaml --force
foundation-utils docker update --force

# Restart a specific service
foundation-utils docker restart -s <service-name>

# List containers (docker compose ps)
foundation-utils docker list

Programmatic Usage

import { Command } from 'commander';
import {
  registerCommands,
  dbEnd,
  dbExport,
  dbImport,
  dbList,
  dbRestore,
  dockerBackup,
  dockerList,
  dockerRestart,
  dockerUpdate
} from '@tryhuset/foundation-utils';

// Attach all db + docker subcommands to a Commander program
const program = new Command();
registerCommands(program);

// End all active sessions
await dbEnd();

// List sessions
await dbList({ active: true });

// Restore a session by ID
await dbRestore({ sessionId: 'abc123', force: true });

// Export database backup
await dbExport({ path: './backup' });

// Import from backup
await dbImport({ path: './backup' });

// Create backup only
await dockerBackup();

// Update Docker images (default: ./compose.yaml)
await dockerUpdate({ force: true });

// Restore stack from backup compose file (same as: docker backup --restore <path>)
await dockerUpdate({ backupFile: './docker_image_backups/docker-compose_20260101T120000.yaml', force: true });

// Restart a service
await dockerRestart({ service: 'api' });

// List containers
await dockerList();

License

MIT