@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 service(s) (interactive multi-select, or -s to skip)
foundation-utils docker restart
foundation-utils docker restart -s <service-name>
foundation-utils docker restart -s api worker

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

# Container logs (interactive service picker; or pass -s / --all)
foundation-utils docker logs
foundation-utils docker logs --all
foundation-utils docker logs -s <service-name> --follow
foundation-utils docker logs -n 200

# Restore stack from a saved backup (interactive list of docker-compose_*.yaml)
foundation-utils docker restore
foundation-utils docker restore -d ./docker_image_backups
foundation-utils docker restore ./docker_image_backups/docker-compose_20260101T120000.yaml
foundation-utils docker restore --force

docker logs – Runs docker compose logs. With no -s, opens an interactive list (all services or a single service from docker compose config --services). Use --all to skip the picker and show every service. Use -s, --service to target one service without prompting. --follow and -n, --tail work as in Docker.

docker restart – Runs docker compose restart. With no -s, opens an interactive checkbox (space to toggle, enter to confirm) from docker compose config --services. Use -s, --service <names...> for one or more services without prompting, e.g. -s api worker.

docker restore – Lists backups under ./docker_image_backups (newest first) and prompts you to pick one, then runs the same flow as docker backup --restore. Pass a path to skip the list. Use -d, --dir to scan another folder.

Knox Manage device management

Manages Samsung Knox Manage devices in a configured device group. The device picker is sorted alphabetically by mobileId.

# Reboot interactively (checkbox with "Select all" toggle)
foundation-utils knox reboot

# Reboot every eligible device — for cron
foundation-utils knox reboot --all

# Reboot only Activated (status A) devices
foundation-utils knox reboot --all --activated-only

# Custom env file (e.g. for cron pointing at server/.env)
foundation-utils knox reboot --all -e /path/to/server/.env

Required environment variables (set them in server/.env):

• KNOX_BASE_URL — regional Knox Manage URL, e.g. https://eu04.manage.samsungknox.com
• KNOX_CLIENT_ID — short API client id from the Knox admin UI
• KNOX_CLIENT_SECRET — API client secret
• KNOX_TENANT_ID — tenant id (combined with the client id as {clientId}@{tenantId} for OAuth)
• KNOX_GROUP_ID — device-group identifier as shown in the Knox admin UI (e.g. Development); required

Programmatic Usage

import { Command } from 'commander';
import {
  registerCommands,
  dbEnd,
  dbExport,
  dbImport,
  dbList,
  dbRestore,
  dockerBackup,
  dockerList,
  dockerLogs,
  dockerRestart,
  dockerRestore,
  dockerUpdate,
  knoxReboot
} 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 });

// Interactive restore (list backups, then pick) or pass a path
await dockerRestore();
await dockerRestore({ backupCompose: './docker_image_backups/docker-compose_20260101T120000.yaml' });

// Logs: interactive picker, or allServices / explicit service
await dockerLogs({ follow: true, tail: 200 });
await dockerLogs({ allServices: true, follow: true });
await dockerLogs({ follow: true, tail: 200, service: 'api' });

// Restart (interactive multi-select) or pass service(s)
await dockerRestart();
await dockerRestart({ service: 'api' });
await dockerRestart({ services: ['api', 'worker'] });

// List containers
await dockerList();

// Reboot Knox devices (interactive by default, or pass all)
await knoxReboot();
await knoxReboot({ all: true });
await knoxReboot({ all: true, activatedOnly: true, env: '/path/to/server/.env' });

License

MIT