The Simpcn handbook
CLI commands
Three commands: initialize, inspect, and migrate. Application builds remain separate.
init — create configuration
npx simpcn init
npx simpcn init --yes --framework next --provider s3 --bucket YOUR_EXISTING_BUCKET --prefix assetsInteractive initialization selects a framework and provider. Framework values are next, vite, or core; provider values are s3, minio, or r2. Edit endpoint and public delivery URL after initialization, or pass --endpoint and --public-base-url explicitly.
--yes skips prompts. --skip-install avoids automatic adapter installation. --force replaces an existing configuration; use it deliberately. Initialization never edits framework config, creates buckets, or changes access policies. If adapter installation fails, the generated configuration is retained.
plan — review without changes
npx simpcn plan
npx simpcn plan --check-remote
npx simpcn plan --check-remote --overwriteThe default plan scans and hashes local files without contacting storage. --check-remote checks object metadata with HEAD requests and reports reconciliation actions; it uploads nothing. Adding --overwrite previews replacement behavior. Remote checking needs credentials and an accessible storage API.
migrate — upload and verify
npx simpcn migrateMigration reconciles local inventory and remote state, uploads required assets, and records verification. Matching assets can be skipped. Successful progress is preserved if other files fail; rerun the command after addressing the failure.
npx simpcn migrate --overwriteReview conflicts before overwriting. Removed local assets are reported, never deleted remotely. Original local assets and source files are retained.
Shared options
| Option | Purpose / default |
|---|---|
--config, -c | Explicit TypeScript configuration path. |
--root | Asset directory; defaults to public. |
--provider, --endpoint, --bucket, --region, --prefix | Override storage target settings. |
--public-base-url | Public delivery root, including prefix. |
--exclude | Repeatable glob; replaces configured exclusions. |
--state-file, --manifest-file | Override local state and inventory paths. |
--concurrency, --hash-concurrency | Concurrent assets: 4; hash workers: 8. |
--max-attempts, --retry-delay-ms | Network attempts: 3; initial delay: 200ms. |
--cache-control | Object cache policy. |
--json | Structured stdout without progress output. |
npx simpcn --help
npx simpcn --version
npx simpcn plan --jsonUse NO_COLOR=1 to disable colors. Exit codes: 0 success, 1 execution failure or conflicts, 2 usage/configuration error, 130 cancellation.
A CI sequence
npm ci
npm run buildThis assumes a committed npm lockfile, configured framework integration, original assets, and matching simpcn/deployment-state.json from a successful migration. Generated files under simpcn/.build/ are recreated during the build. Storage credentials are only needed if you choose to run migration as a separate CI step.
No simpcn build, deploy, sync, or purge command exists.