spade upload

The spade upload command validates the current block collection and packages it into a local tarball, in preparation for cloud distribution. This is the command that exists today — there is no spade publish command in the CLI (confirmed: no publish is registered as a Use: string anywhere under cli/cmd/).

spade upload only gets as far as packaging: the server-side upload API isn't wired up yet, so the command prints a note to that effect and stops. It does not send the tarball anywhere.

Usage🔗

spade upload

No arguments are required. The command operates on the collection in the current working directory.

What it does🔗

1. Validate the collection🔗

Runs the same manifest and structural checks as spade check against the working tree. If any errors are found, they're printed and the command exits with status 1 without packaging anything.

2. Detect language and read metadata🔗

The collection's language is detected the same way spade install detects it (Cargo.toml / go.mod / pyproject.toml / package.json, defaulting to R). The collection name and version are read from the language's manifest, falling back to the current directory's name and 0.1.0 respectively if either can't be read.

3. Package into a tarball🔗

The collection is archived into <name>-<version>.tar.gz in the current directory. The archive always includes the blocks/ directory and the language manifest file (Cargo.toml, pyproject.toml, go.mod, package.json, or DESCRIPTION), plus language-specific source:

4. Report status🔗

Collection packaged: my-collection-0.1.0.tar.gz
Note: Upload endpoint is not yet configured. The server-side upload API will be integrated when the PocketBase server is available.

Example🔗

cd my-collection
spade upload

Collection packaged: my-collection-0.1.0.tar.gz
Note: Upload endpoint is not yet configured. The server-side upload API will be integrated when the PocketBase server is available.

See also🔗

• spade check for running the same validation independently
• spade install for building and registering a collection locally
• spade login for authenticating to a Spade server (used today by spade data, not by spade upload)

Planned: submit-by-reference publishing🔗

The section below describes a future direction, not current behavior. There is no spade publish command today, and nothing in cli/cmd/ implements it — treat everything past this point as a design sketch, not documentation of shipped functionality.

The idea is a spade publish command that, unlike spade upload, would not package or transmit an artifact at all. Instead it would submit a reference — (repo_url, commit_sha, collection_name, version) — for a commit already pushed to a git remote, and a cloud registry would do the rest: clone the repository at that exact commit, screen the source, build the artifact in a bundler image, sign it, and store it.

Preconditions envisioned for spade publish🔗

1. A spade login session — the submission would be authenticated as the developer.
2. A clean working tree — no uncommitted changes.
3. A pushed HEAD — the current commit reachable on the configured remote.

The reasoning: the registry would screen source and then build from that same commit SHA, so the artifact it signs is provably the result of running the build pipeline against the exact code that was screened. Allowing publication of local, unpushed changes would let the screened source and the deployed source diverge, defeating the point of screening.

Envisioned lifecycle🔗

None of this exists yet. Until it does, spade upload's tarball-packaging step above is the only implemented piece of the collection-distribution story, and even that stops short of actually transmitting anything.