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:
It reads and writes documents, comments, contacts, capabilities and keys.
It converts documents to and from markdown.
It publishes whole folders, including this documentation.
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 |
|---|---|
| The entry point: global options, server resolution, command registration. |
| One file per command group: |
| Key lookup across the OS keyring, the desktop app's local vault file (which can sync with the vault service) and environment variables. |
| The push, pull and dev loop for this |
| The fixture suite that starts a real daemon and web server. |
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 testsReleases 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.
See also
Package publishing, for how the CLI reaches npm.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime