The Seed CLI (seed-cli) is a command-line program that reads and writes the Hypermedia network. For example, seed-cli document get <id> prints a document as markdown. You can edit that markdown and send it back.
The CLI signs everything on your machine with a key you hold. It talks to any Seed site over the Seed API. AI agents use it too: a Claude Code session with the seed-cli skill runs these same commands.
Install
npx -y @seed-hypermedia/cli --help # run without installing
npm install -g @seed-hypermedia/cli # or install; provides `seed-cli` and `seed-hypermedia`It needs Node 18 or newer. The package is one bundle with the SDK inside. Each change to the CLI on the main branch is published as a new patch version, so npx …@latest follows main. The CLI program page says how to run it from a checkout.
Global options
Option | Meaning |
|---|---|
| the Seed web server to talk to (default |
| development environment: |
| structured output ( |
| colourised JSON or YAML, or markdown rendered for the terminal |
| one tab-separated line per item, no status messages |
| a desktop or daemon |
| print the version; print help |
The CLI picks the server in this order: --dev, --server, the SEED_SERVER variable, server in ~/.seed/config.json, then https://hyper.media. One exception: an https:// URL given as an id talks to that URL's own origin, whatever the server setting.
Output rules: stdout carries only data, so you can pipe it safely. Status lines go to stderr as ✓, ✗, ℹ and ⚠. document get (JSON with -m), draft get and document create --dry-run print markdown by default. Everything else prints JSON. Exit codes are 0 and 1 only. Validation and verification failures also exit 1.
Config lives in ~/.seed/config.json (server, defaultAccount, vaultPath), written with seed-cli config --server <url>, --vault-path <path>, --show, and seed-cli key default <name>.
Variable | Effect |
|---|---|
| default server, below |
| the contents of an unencrypted |
| a BIP-39 phrase used the same way; setting both is an error |
| an explicit |
| the base64 32-byte key-encryption key that unwraps the vault's data key, for machines without a keychain |
| where drafts are written |
Keys and signing
The CLI signs on your machine. It never asks a daemon or a vault service to sign. It looks for keys in three places, in this order:
The environment: SEED_CLI_KEYFILE or SEED_CLI_MNEMONIC.
The encrypted vault of a Seed app or daemon on the same machine. The CLI only reads it.
The OS keyring, where key generate and key import save keys.
-k, --key <name> picks a key by name or by account id. A key's name and its account id are different things, and you can use either. Without -k, the default key is the configured defaultAccount, else a key named main, else the first vault account, else the default key of the keyring. Keys explains all of this.
With --dev, the CLI looks for the vault in the Seed-dev app folder. An app started with ./dev keeps its data in Seed-local, so point the CLI at that vault with --vault <path>.
Writing into a space you do not own takes a capability. A capability is a permission that the space gave your key. -a, --account <uid> on document create and account profile set finds that capability (a WRITER or AGENT one) and attaches its CID to the blob you publish. document update and document delete do the same lookup for the document's own space without a flag. See Permissions.
Ids
Any command that takes an id accepts hm://<uid>/<path>, a bare <uid>, or an https:// page URL, which is resolved through the site's OPTIONS headers. Given to document get, a path ending in :directory lists the children. Comment ids are <author>/<tsid>. Web URLs with a comments panel are recognised as comment ids. See URLs.
document
Command | What it does |
|---|---|
| prints a document or comment as markdown with YAML frontmatter and |
| creates a document from |
|
|
|
|
| diffs |
| publishes a tombstone Ref |
| a new path on the source's history |
| a version Ref at the destination and a redirect at the source |
| a redirect Ref; with |
| the change history ( |
| interaction counts |
| checks the document against its effective attributes schema; exit 1 on violations |
| fetches a raw block |
Metadata precedence on create is defaults, then frontmatter or PDF, then flags, then --metadata. file:// links in image blocks and in icon, cover and logo metadata are uploaded as IPFS files and rewritten to ipfs://. After creating a document two or more levels deep, the CLI adds a link card to the parent document. It skips this when the parent does not exist, already links the child, lists its own children with a query block, or is a typed collection. The SDK applies the genesis rule that makes a new document distinct from the home document. See SDK.
Two things are refused before anything is published: frontmatter whose YAML does not parse (quote a value that contains a colon, name: "A: B"), and a ```mermaid fence that mermaid cannot parse. The same checks run on document update, comment create and space push.
comment
Command | What it does |
|---|---|
| one comment |
| comments on a document |
| a comment; the body is markdown. A |
| replaces the comment, keeping its thread position |
| a tombstone |
| threaded discussions |
capability, contact, account
Command | What it does |
|---|---|
| signs and publishes a capability from your key to another account, optionally scoped to a path |
| a contact: a named reference to another account |
| a tombstone |
| contacts by or about an account |
| account lookups |
| publishes a profile blob; |
| who may write to a space or path |
key
Command | What it does |
|---|---|
| a new key in the OS keyring; a name may use letters, digits, hyphens and underscores only |
| a key from a BIP-39 phrase |
| every key the CLI finds in the vault and the keyring, with its source |
| keyring keys only for rename and remove; the CLI never modifies a vault |
| prints the account id without storing anything |
| writes a |
draft
Drafts are local files the desktop app also sees. draft create -f <file> parses and validates input and saves it as <slug>_<id>.md in the drafts/ folder of the desktop app's user data directory (Seed, or Seed-local with --dev; SEED_CLI_DRAFTS_DIR overrides, and -o <path> writes to a path you choose), with an entry in the app's index.json draft index. --edit <hm-url> marks it as an edit of an existing document, --location <hm-url> as a new child, and --visibility PUBLIC|PRIVATE sets its visibility. draft get <slug>, draft list and draft rm [<slug>] [--all] [--force] complete the set. An agent that writes drafts instead of publishing lets a person review in the app. See Using Seed from your own agent.
space
Command | What it does |
|---|---|
| writes every document of a space as lossless markdown, home document as |
| publishes the directory, diffing existing documents by block id and detecting moves; |
| also downloads every file the documents link into |
| saves the whole space in one zip. |
| a blob archive is published as is to |
| edits the directory in the desktop dev app under a throwaway key |
Publish a folder explains the loop, and the markdown dialect is the file format.
blob and schema
Command | What it does |
|---|---|
| prints a blob as DAG-JSON |
| checks a dag-json value against a schema (a file, |
| publishes a value as a DAG-CBOR blob, validated and linked to its schema |
| adds the signed envelope ( |
| checks the signature and the schema |
| a schema with its CID; |
| is this a valid Hypermedia schema |
To publish a schema of your own, use document create --schema-definition <file>. Hypermedia Schemas and the one-page reference show the whole workflow.
search, query, attributes, citations, activity
Command | What it does |
|---|---|
| full-text search; |
| a directory listing |
| documents by attribute, anywhere with |
| shorthand for a |
| which attribute keys documents use and the values a key takes |
| documents that link here |
| the event feed |
Working with it
In the Seed app
Drafts the CLI writes appear in the app's draft list. The CLI can read keys the app holds in its vault on the same machine.
SDK
Each command is a few SDK calls plus one PublishBlobs request. The CLI source is the best set of worked examples.
Seed API
The CLI talks to the Seed API. The one exception is space dev, which registers its throwaway key in the dev daemon over gRPC-web.
Agents
The CLI is the recommended way for an external agent to touch Seed. Run it as npx -y @seed-hypermedia/cli@latest …, keep a bot key with a delegated capability, and prefer draft create when a person should review before anything is published. Using Seed from your own agent has the workflow. Seed Agents expose the same operations through their read and write verbs.
See also
The Seed CLI app page, for where the code lives and how it is tested
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime