Seeding a File Into a Project

swarmfile-seed places one local file at a path inside a project over the public API - without mounting a drive. Use it from a script or a CI job to drop a release artifact, a fixture, or a large asset where you want it.

It chunks the file, seals each block client-side when a key is configured, and registers the entry - the same pipeline the desktop mount and the migration tool run. The file is streamed, so a multi-gigabyte source does not have to fit in memory.

This guide covers the standalone open-source build of swarmfile-seed (API-key auth, every target given as a flag), published at swarmfile-seed under MIT/Apache-2.0. The Desktop App also puts a swarmfile-seed on PATH, but that bundled build is a different tool: it takes its project and credentials from the environment and has no --org-id, --project-id, --token or --branch flags. Its reference is swarmfile-seed. On a machine with both, the first one on your PATH wins; swarmfile-seed --help tells them apart (the standalone's summary says "standalone, API-key auth").

Install#

curl -fsSL https://get.swarmfile.com/seed | sh

The install script downloads the release for your machine, verifies its checksum, and installs swarmfile-seed into ~/.local/bin (or /usr/local/bin), warning if that directory is not on your PATH. A binary archive and the source are on the swarmfile-seed public project.

Use#

Set a token, then point it at a file and a destination path:

export SWARMFILE_API_KEY=sf_pat_…          # a personal access token, or an org API key

swarmfile-seed \
  --hub-url https://hub.swarmfile.com \
  --org-id my-org --project-id <project-id> \
  --file ./build/app-2.1.0.zip \
  --path /Releases/app-2.1.0.zip

• --path is the destination inside the project. Missing parent directories are created. The file name is the last path segment.
• --token passes the token directly; it defaults to $SWARMFILE_API_KEY.
• --org-id accepts the org's id or its slug.
• --branch targets a non-default branch; omit it for the hub's configured default.
• Chunking. Fixed-size by default. --cdc uses content-defined chunking (fast, dedup-friendly for large files that change little); --auto-profile picks a per-type profile (the same AEC and media profiles the mount's own writes use). --cdc and --auto-profile are mutually exclusive.

What it does when something is already there#

The hub treats a create at an existing name as get-or-create - it will not overwrite. If a file with the same name but different content already sits at --path, swarmfile-seed fails loudly rather than reporting a false success; delete the existing entry or pick another path. An empty file registers as a zero-byte entry (no content address), the same way the mount represents one.

Sealing#

With a managed project, the hub-held key is fetched and every block is sealed before upload, so the hub never sees plaintext. An SWARMFILE_ENCRYPTION_KEY environment variable is used as-is - supplying it also lets you seed an end-to-end-encrypted project. With no key at all, the file is stored plaintext.

Exit codes#

0 success; 1 a failure, including a bad --path or a refused upload; 2 a flag/usage error from the argument parser. A refusal is on stderr.