swarmfile-migrate

swarmfile-migrate bulk-imports data you already have into a Swarmfile project: a local directory, a flat list of file paths, or an S3-compatible bucket. It's a standalone binary - no running engine required - meant for the first-time import of an existing archive, not for day-to-day file operations.

This page is the flag reference. For a practical walkthrough with a worked example, see Migrating Existing Data.

Run with --dry-run first. It walks the source and reports what would be migrated without uploading anything, which is the safe way to check your exclude patterns and source/destination settings before committing to a real run.

Source selection#

Pick exactly one source: a local directory, a flat file list, or an S3-compatible bucket.

Flag	Description
`--source`	Local directory source
`--source-list`	Flat file-list source
`--source-root`	Root to resolve relative paths in `--source-list` against
`--source-s3-bucket`	S3-compatible source bucket
`--source-s3-prefix`	Prefix within the S3 bucket to migrate
`--source-s3-endpoint`	S3-compatible endpoint URL
`--source-s3-region`	Default `us-east-1`

Destination#

Flag	Description
`--root-path`	Destination path inside the project. Default `/`
`--hub-url`	Your hub URL, e.g. `https://hub.swarmfile.com` (or your self-hosted hub's URL). Defaults to `$SWARMFILE_HUB_URL` if set, otherwise the hosted hub (`https://hub.swarmfile.com`) - so a machine whose environment already names its hub does not need this flag
`--org-id`	Target organization
`--project-id`	Target project
`--oidc-issuer`	OIDC issuer for authenticated hub access
`--oidc-client-id`	OIDC client ID
`--oidc-refresh-token`	OIDC refresh token

Exclusions#

Flag	Description
`--exclude`	Gitignore-style exclude pattern. Repeatable.
`--exclude-from`	File containing exclude patterns, one per line

Reliability#

Flag	Description
`--concurrency`	File-level concurrency. Default `8`
`--block-concurrency`	Block-upload concurrency per file. Default `4`
`--retry`	Retry attempts per failed transfer. Default `0`
`--verify`	Verify each upload against the source with a CID/hash comparison
`--state-db`	Local state DB path. Tracks what's already uploaded and enables resuming a re-run
`--report-json`	Write a JSON report of the run
`--start-at`	Resume marker to start from

Safety#

Flag	Description
`--dry-run`	Report what would be migrated without uploading anything
`--force`	Re-migrate files already registered/uploaded in a prior run, instead of skipping them

Examples#

Local directory, skipping cache and scratch files, with post-upload verification:

swarmfile-migrate --source /Volumes/nas/ProjectArchive \
  --hub-url https://hub.swarmfile.com \
  --org-id acme-films --project-id feature-01 \
  --exclude "*.cache" --exclude "**/tmp/**" \
  --state-db ./migrate-state.db \
  --verify

S3-compatible bucket, previewed with --dry-run before the real run:

swarmfile-migrate --source-s3-bucket project-archive \
  --source-s3-prefix renders/2025 \
  --source-s3-endpoint https://s3.us-west-000.backblazeb2.com \
  --hub-url https://hub.swarmfile.com \
  --org-id acme-films --project-id feature-01 \
  --dry-run