# 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-seed` is 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, see [`swarmfile seed enable`](https://swarmfile.com/docs/cli/swarmfile) on the full client, covered in [Self-Hosted Seed Nodes](https://swarmfile.com/docs/admin/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`**, and **`SWARMFILE_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

```bash
SWARMFILE_PROJECT_ID=<project-id> swarmfile-seed --file ./plan.dwg \
  --path "/Projects/Site A/plan.dwg" \
  --hub-url https://hub.swarmfile.com --auto-profile
```