The Seed CLI
The Seed CLI is the terminal client for Hypermedia, and this page says where its code is, how it reaches a site, where it finds keys and settings, and how it is built and released.

The Seed CLI, seed-cli, is the terminal client for the Hypermedia network. People, scripts and coding agents use it to read and write from a shell. It needs no daemon of its own: it signs on your machine and talks to a site over HTTPS.

The CLI does three kinds of work:

This page is the map for people who change the CLI. Every command and flag is in the CLI reference.

Where the code is

The code is in frontend/apps/cli, package @seed-hypermedia/cli. The package is published to npm with two binaries, seed-cli and seed-hypermedia. It is written in TypeScript on commander, and it is developed and tested with Bun. bun build --target node bundles it 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 local vault file (which can sync with the vault service) 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 repository, and the published build bundles them.

How it talks to the daemon

It does not need one. Every command goes to a site. A read is a GET request to the site's /api/<Key> routes. A write is a set of signed blobs sent with the PublishBlobs action. See Seed API. src/index.ts decides which site to use. The CLI reference gives the order of the flags, the variable and the config file.

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

Configuration

The CLI has three sources of settings: global flags, environment variables, and ~/.seed/config.json. The CLI reference lists them all.

Signing keys come from the environment, the desktop app's vault.json, or the OS keyring. The lookup is in src/utils/keyring.ts and src/utils/keys.ts. Keys explains each store and how to create, import and delegate keys.

Running it

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. Package publishing explains how the version is chosen.

Working with it

In the Seed app

The CLI reads the same keyring entries and the same local vault file, vault.json, as the desktop app. So you can use an account that you created in the app from the terminal on the same machine.

Agents

A coding agent such as Claude Code, with the seed-cli skill, uses Hypermedia through these commands. Using Seed from your own agent shows how. Seed Agents do not use the CLI. They call the Seed API directly.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime