# 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](https://swarmfile.com/public/swarmfile/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`](https://swarmfile.com/docs/cli/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

```bash
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](https://swarmfile.com/public/swarmfile/swarmfile-seed) public project.

## Use

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

```bash
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.

![Engine-free and mount-free: swarmfile-seed places one local file at an exact project path, and swarmfile-mirror copies a subtree from one project into another - the same chunk, seal and upload pipeline the whole ecosystem shares.](https://swarmfile.com/demo/oss-tools.cast)

## 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.