The Seed CLI

Where the seed-cli code lives, how it reaches a site or a local desktop app, where it keeps its keys and settings, and how it is built and released.

Seed Hypermedia

24 September 2026, 11:28

Seed Hypermedia

24 September 2026, 11:28

ContentPeople8CommentsCitationsAttributes0

The Seed CLI, seed-cli, is the terminal client for the Hypermedia network. It reads and writes documents, comments, contacts, capabilities and keys, converts documents to and from markdown, and publishes whole folders, including this documentation. It needs no daemon of its own. It signs locally and talks to a site over HTTPS. This page is the contributor's map. Every command and flag is in the CLI reference.

Where the code is

frontend/apps/cli, package @seed-hypermedia/cli, published to npm with two binaries, seed-cli and seed-hypermedia. It is written in TypeScript on commander, developed and tested with Bun, and bundled with bun build --target node into dist/index.js, so the published package runs on plain Node.

Path	What it holds
`src/index.ts`	The entry point: global options, server resolution, command registration.
`src/commands/`	One file per command group: `document`, `comment`, `capability`, `contact`, `account`, `key`, `draft`, `space`, `blob`, `schema`, `search`, `query`.
`src/utils/keyring.ts`, `src/utils/keys.ts`	Key lookup across the OS keyring, the desktop app's vault file and environment variables.
`src/sync-hypermedia.ts`	The push, pull and dev loop for this `hypermedia/` folder.
`src/test/`	The fixture suite that starts a real daemon and web server.

The CLI builds and signs blobs with @seed-hypermedia/client, the SDK. A few files, the folder sync among them, also import from @shm/shared without declaring it. They work inside the monorepo, and the published build bundles them.

How it talks to the network

By default every command goes to https://hyper.media. The server is chosen in this order: --dev (which means https://dev.hyper.media and the dev keyring), --server <url>, the SEED_SERVER environment variable, the server value in ~/.seed/config.json, and finally hyper.media. Reads are GET requests to the site's /api/<Key> routes. Writes are signed blobs sent with the PublishBlobs action. See The web API.

seed-cli space dev is the one mode that talks to a local node. It publishes a folder into the running desktop app through the app's API bridge, http://localhost:58004 by default, and watches the daemon at http://localhost:58001, writing edits made in the app back to disk. ./dev hm-sync runs that loop for this folder.

Keys and configuration

Source	Meaning
OS keyring	Service `seed-daemon-main`, or `seed-daemon-dev` with `--dev`: the same entries the desktop app's daemon uses.
Desktop vault file	The desktop app's `vault.json`, found automatically or named with `--vault` or `vaultPath` in the config; searched before the keyring.
`SEED_CLI_KEYFILE`, `SEED_CLI_MNEMONIC`	A key for CI or a server, as an unencrypted `.hmkey.json` or a BIP-39 phrase. Only one may be set.
`~/.seed/config.json`	Saved settings such as `server` and `vaultPath`.

Keys explains how to create, import and delegate keys.

Build, test, release

cd frontend/apps/cli
bun run src/index.ts --help   # run from source
pnpm build                    # bundle into dist/
pnpm test                     # fixture suite against a real daemon and web server
pnpm test:unit                # fast unit tests

Releases are automatic: the publish-client.yml workflow builds and publishes the CLI and the SDK to npm when their sources change on main. The version in the repository's package.json is not the published version, so check npm for what users have.

Working with it

In the Seed app

The CLI reads the same keyring entries and vault file as the desktop app, so an account created in the app is usable from the terminal on the same machine.

Agents

A coding agent such as Claude Code with the seed-cli skill drives Hypermedia through these commands; Building agents on Seed shows how. Seed Agents do not use the CLI. They call the Seed API directly.