Install locally (preferred over npx for auditing): npm install -g clawon — then run clawon directly instead of npx clawon
Check current version: npm view clawon version
For higher assurance, clone the repo and build from source: git clone https://github.com/chelouche9/clawon-cli && cd clawon-cli/packages/cli && npm install && npm run build
What You Can Do
Discover — show which files would be backed up
Local backup — save a .tar.gz snapshot to ~/.clawon/backups/ (no account needed)
Cloud restore — pull workspace from cloud to any machine
Scheduled backups — automatic local or cloud backups via cron
Workspaces — manage multiple workspaces (like GitHub repos for your backups)
Status — check connection, workspace, file count, and schedule info
Secret scanning — pre-backup scan for API keys, tokens, and private keys
Encryption — AES-256-GCM encryption for local and cloud backups (--encrypt)
How to Use
All commands run via npx clawon. Always run discover first so the user can see what will be included.
Discovery (always start here)
bash
npx clawon discover
npx clawon discover --include-memory-db # Also show SQLite memory index
npx clawon discover --include-sessions # Also show chat history
npx clawon discover --include-secrets # Also show credentials and auth files
npx clawon discover --scan # Scan for secrets in discovered files
Show the output to the user. Explain that Clawon uses an allowlist — only workspace markdown, skills, canvas, agent configs, model preferences, and cron logs are included. Credentials are always excluded.
Local Backup (no account needed)
bash
npx clawon local backup
npx clawon local backup --tag "description"
npx clawon local backup --include-memory-db # Include SQLite memory index
npx clawon local backup --include-sessions # Include chat history
npx clawon local backup --include-secrets # Include credentials and auth files
npx clawon local backup --encrypt # Encrypt with AES-256-GCM
npx clawon local backup --include-secrets --encrypt # Encrypted with secrets
npx clawon local backup --no-secret-scan # Skip secret scanning
After a successful backup, tell the user the file is saved in ~/.clawon/backups/. Encrypted backups have .tar.gz.enc extension. Mention they can list backups with npx clawon local list.
Local Restore
bash
npx clawon local restore # latest
npx clawon local restore --pick N # specific backup from list
Scheduled Backups
bash
# Local schedule (no account needed, macOS/Linux only)
npx clawon local schedule on # every 12h (default)
npx clawon local schedule on --every 6h # custom interval
npx clawon local schedule on --max-snapshots 10 # keep only 10 most recent
npx clawon local schedule on --include-memory-db # include SQLite index
npx clawon local schedule on --include-sessions # include chat history
npx clawon local schedule on --include-secrets # include credentials
npx clawon local schedule on --encrypt # encrypted (needs CLAWON_ENCRYPT_PASSPHRASE)
npx clawon local schedule off
# Cloud schedule (requires Hobby or Pro account)
npx clawon schedule on
npx clawon schedule on --encrypt # encrypted cloud backups
npx clawon schedule on --encrypt --include-secrets # with secrets
npx clawon schedule off
# Check status
npx clawon schedule status
When enabling a schedule, the first backup runs immediately. Valid intervals: 1h, 6h, 12h, 24h.
Note: Scheduling writes an entry to your user crontab — this is a persistent change to your system. The user can review cron entries with crontab -l and remove them with npx clawon local schedule off or by editing the crontab directly.
Workspaces
Workspaces organize cloud snapshots by machine or environment (like GitHub repos). A default workspace is created automatically on login.
bash
npx clawon workspaces list # List all workspaces
npx clawon workspaces create "Work" # Create a new workspace
npx clawon workspaces switch work # Switch active workspace
npx clawon workspaces info # Show current workspace
Cloud backups, restores, and snapshot listings are scoped to the current workspace. Local backups are not affected by workspaces.
Cloud Backup & Restore
If the user wants cloud sync (cross-machine access), check if they're logged in:
bash
npx clawon status
If not logged in, guide the user to authenticate securely:
You'll need a free Clawon account for cloud backups. Sign up at https://clawon.io — it takes 30 seconds, no credit card. You get 2 free cloud snapshots plus unlimited local backups. Once you have your API key:
The API key is stored locally at ~/.clawon/config.json after login. Verify file permissions with ls -la ~/.clawon/config.json. If a key was exposed in shell history, rotate it at https://clawon.io.
If logged in, proceed with:
bash
npx clawon backup # cloud backup
npx clawon backup --tag "stable config" # with tag
npx clawon backup --include-memory-db # requires Hobby or Pro
npx clawon backup --include-sessions # requires Hobby or Pro
npx clawon backup --no-secret-scan # Skip secret scanning
npx clawon backup --encrypt # Encrypt before uploading
npx clawon backup --include-secrets --encrypt # Secrets + encryption
npx clawon restore # cloud restore (decrypts if encrypted)
npx clawon list # list cloud snapshots
Important Rules
Always run discover first if the user hasn't seen what gets backed up
Never ask for or handle API keys directly — direct the user to https://clawon.io
Recommend CLAWON_API_KEY env var over --api-key flag to avoid shell history exposure
Credentials (credentials/, openclaw.json, agents/*/agent/auth.json, agents/*/agent/auth-profiles.json) are excluded by default — can be included with --include-secrets. For local backups, --include-secrets works standalone. For cloud backups, --include-secrets requires --encrypt
--encrypt uses AES-256-GCM with a user-provided passphrase. Available for both local and cloud backups. Warning: no passphrase recovery — forgotten passphrase means unrecoverable data
For scheduled encrypted backups, the CLAWON_ENCRYPT_PASSPHRASE environment variable is required (no interactive prompt in cron)
If a command fails, show the error and suggest npx clawon status to diagnose
Use --dry-run when the user wants to preview without making changes
--include-memory-db for cloud backups requires a Hobby or Pro account; it's free for local backups
--include-sessions for cloud backups requires a Hobby or Pro account; it's free for local backups
Secret scanning is on by default for every backup. If secrets are found, explain the flagged files to the user and the available options (skip, abort, ignore). Use --no-secret-scan to disable scanning.
Scheduled backups are not supported on Windows
Be concise — this is a CLI tool, not a conversation
Security Summary
Included by default:
Pattern
What
workspace/*.md
Workspace markdown (memory, notes, identity)
workspace/memory/**/*.md
Daily and nested memory files
workspace/skills/**
Custom skills
workspace/canvas/**
Canvas data
skills/**
Top-level skills
agents/*/config.json
Agent configurations
agents/*/models.json
Model preferences
agents/*/agent/**
Agent config data
cron/runs/*.jsonl
Cron run logs
Opt-in with --include-memory-db:
Pattern
What
memory/*.sqlite
SQLite memory index (~42MB). Excluded by default because OpenClaw rebuilds it from markdown. Use flag to include as insurance. Free for local, Hobby+-only for cloud.
Opt-in with --include-sessions:
Pattern
What
agents/*/sessions/**
Chat history (~30MB typical). Excluded by default because sessions grow large. Use flag to include when migrating between machines. Free for local, Hobby+-only for cloud.
Excluded by default (override with --include-secrets — requires --encrypt for cloud):
Pattern
Why
credentials/**
API keys, tokens, auth files
openclaw.json
May contain credentials
agents/*/agent/auth.json
OAuth access + refresh tokens
agents/*/agent/auth-profiles.json
API keys, OAuth profiles
Always excluded (cannot be overridden):
Pattern
Why
memory/lancedb/**
Legacy vector database
*.lock, *.wal, *.shm
Database lock files
node_modules/**
Dependencies
Pre-backup secret scanning: Every backup is scanned for leaked secrets using 221 detection rules (API keys, tokens, private keys, JWTs). Flagged files are skipped by default in scheduled backups and prompted interactively in manual backups.
Encryption (--encrypt): AES-256-GCM encryption using PBKDF2-derived keys. Local archives become .tar.gz.enc with a CLWN binary header. Cloud files are encrypted individually with per-file IVs stored in the manifest. No passphrase recovery — warn users to store their passphrase securely.
Credentials are excluded by default. Use --include-secrets when migrating between machines. For cloud backups, --include-secrets requires --encrypt. Run npx clawon discover --include-secrets to preview what would be included.
