swarmfile-seed
swarmfile-seed seeds a single local file into the Swarmfile hub: it reads the file, chunks it, uploads the resulting blocks, and registers a file entry (creating any missing parent directories along the way) at a virtual path you specify. It's a standalone binary with no subcommands - one invocation seeds one file. Every desktop installer carries it, and the Linux .deb, macOS .pkg and Windows installers put it on PATH (/usr/bin on Linux, /usr/local/bin on macOS, or the Windows install folder); a macOS .dmg-only install needs one .pkg (or Diagnostics → Reinstall) run for that entry.
swarmfile-seedis a one-shot ingestion tool, not a persistent process. It uploads the file you point it at and exits. For running a machine as an ongoing, persistent participant in the peer-to-peer swarm, seeswarmfile seed enableon the full client, covered in Self-Hosted Seed Nodes.
Flags#
| Flag | Description |
|---|---|
--file | Path to the local file to upload |
--path | Virtual path in the filesystem (e.g. /Projects/plan.dwg) |
--hub-url | Hub URL. Defaults to $SWARMFILE_HUB_URL, else the hub the install's config.json names, else the build's fallback (https://hub.swarmfile.com in a release build, http://localhost:8787 in a debug build). Override for a self-hosted / Enterprise hub |
--cdc | Use content-defined chunking (FastCDC) instead of fixed-size |
--auto-profile | Auto-select chunking strategy based on file extension (AEC profiles). Conflicts with --cdc |
--file and --path are both required. --path must not be empty or contain empty segments (no leading/trailing/double slashes past trimming) - it's validated before any I/O happens.
Chunking#
By default, swarmfile-seed chunks the file with a fixed chunk size. --cdc switches to content-defined chunking (FastCDC), which tends to deduplicate better across files with small internal shifts. --auto-profile instead picks a chunking strategy per the file's extension using the same AEC (architecture/engineering/construction) profiles the rest of the ingest pipeline uses, and is mutually exclusive with --cdc. If neither flag is passed, fixed-size chunking is used.
What it does not do#
Unlike swarmfile-migrate, swarmfile-seed uploads exactly one file per invocation - there's no directory-walk or file-list mode. It also does not erasure-code the upload - a deliberate scope limit for this single-file admin/seeding tool.
There is no --project-id or --org-id flag; project selection is environment-driven. The entry has to land in a project - the project-scoped metadata route is the only one that can accept a create - so swarmfile-seed resolves it from SWARMFILE_PROJECT_ID (falling back to SWARMFILE_ENCRYPTION_PROJECT_ID when that is the only one set, for the managed-key path) and fails with an actionable error before uploading anything if neither is set. If both are set they must name the same project. Any encryption-key lookup keyed to a project is likewise driven entirely by environment variables rather than a CLI flag. The key sources are:
SWARMFILE_ENCRYPTION_KEY- a static hex-encoded key you supply directly.SWARMFILE_ENCRYPTION_PROJECT_ID- resolve a managed-tier project's hub-held key. This path additionally needs OIDC credentials in the environment:SWARMFILE_OIDC_ISSUER,SWARMFILE_OIDC_CLIENT_ID, andSWARMFILE_OIDC_REFRESH_TOKEN(all three).
Encryption is on by default. If no key source is configured for the invocation, the tool warns and seeds the file as plaintext rather than refusing to run - unless encryption was explicitly requested (any of the above set), in which case it fails instead. To silence the plaintext-mirror warning on a node that is deliberately seeding without encryption, set SWARMFILE_ENCRYPTION_ENABLED=false.
Example#
SWARMFILE_PROJECT_ID=<project-id> swarmfile-seed --file ./plan.dwg \
--path "/Projects/Site A/plan.dwg" \
--hub-url https://hub.swarmfile.com --auto-profile