Backup automation
The backup API returns a gzip archive to your process; keep it in storage you control. For selection, protected restore behavior and recovery, read Backups and restore.
Export
import { writeFile } from 'node:fs/promises';
const archive = await admin.backups.exportWorkspace();
await writeFile(archive.fileName, new Uint8Array(archive.bytes), { mode: 0o600 });Use exportProject(projectId) for a project-scoped archive. bytes contains raw gzip data; do not JSON-stringify or base64 it unless your storage format explicitly requires that.
Exports mask credentials unless includeSecrets: true is passed. Masked values cannot recover working credentials. Secret-bearing archives must be stored with the same care as the keys themselves. Ordinary exports need backups:read; including secrets requires backups:write.
Restore
import { readFile } from 'node:fs/promises';
const bytes = await readFile('workspace.snapshot.json.gz');
const result = await admin.backups.restoreWorkspace({ bytes });
console.log(result.restore);Use restoreProject(projectId, { bytes }) for project scope. Applying recoverable credentials requires includeSecrets: true on restore as well as credentials present in the archive. Workspace operations require All projects in both modes and the appropriate backup permission; restore requires backups:write.
Restore validates scope and data, then applies supported records. It does not rewind settled usage, paid history or external provider actions. A project restore and importing a configuration into a new project are different operations; the latter uses the app’s import flow or its corresponding REST endpoint.
The SDK waits up to ten minutes. A timeout means your process stopped waiting, not that the server rolled back. Inspect the destination before deciding whether to retry. Scope mismatch is refused; an unreadable archive is rejected before application.
CLI
modem-cli backups export --output ./workspace.snapshot.json.gz
modem-cli backups restore --input ./workspace.snapshot.json.gzAdd --project-id for project scope and --include-secrets only when needed. Export replaces an existing destination atomically. --output - writes gzip bytes to stdout; keep status output on stderr separate. Restore requires confirmation or --yes in a noninteractive process. See automation for secret export confirmation and piping.