Seed CLI
The Seed CLI (seed-cli) reads and writes Hypermedia from a terminal, and this page lists how to install it, how it signs, and its commands and flags.

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

-s, --server <url>

the Seed web server to talk to (default https://hyper.media)

--dev

development environment: https://dev.hyper.media plus the dev keyring, the vault in the Seed-dev app folder and drafts in the Seed-local app folder; cannot be combined with --server

--json, --yaml

structured output (--md, the markdown default, is accepted but changes nothing)

--pretty

colourised JSON or YAML, or markdown rendered for the terminal

-q, --quiet

one tab-separated line per item, no status messages

--vault <path>

a desktop or daemon vault.json to read identities from (default: auto-detect)

-V, --version, -h, --help

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

SEED_SERVER

default server, below --server

SEED_CLI_KEYFILE

the contents of an unencrypted .hmkey.json; becomes the signing key for every write

SEED_CLI_MNEMONIC

a BIP-39 phrase used the same way; setting both is an error

SEED_VAULT_PATH

an explicit vault.json; vault errors become fatal

SEED_VAULT_KEK

the base64 32-byte key-encryption key that unwraps the vault's data key, for machines without a keychain

SEED_CLI_DRAFTS_DIR

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

document get <id>

prints a document or comment as markdown with YAML frontmatter and <!-- id:… --> block comments; -m metadata only, -r resolves embeds, mentions and queries, -o <file> writes to a file. Follows redirects and republishes and says so.

document create

creates a document from -f <file> (.md, .json blocks, or .pdf) or stdin. Input and place: -p, --path (default: a slug of the name; / is the home document), --grobid-url (for PDF input), -k, -a.

document create, metadata flags

--name, --summary, --display-author, --display-publish-time, --icon, --cover, --site-url, --layout, --show-outline / --no-show-outline, --show-activity / --no-show-activity, --content-width (S, M or L), --children-type, --seed-experimental-logo, --seed-experimental-home-order, --import-categories, --import-tags, --metadata <json> (any keys, merged last)

document create, schema and safety flags

--attributes-schema <ref>, --child-attributes-schema <ref>, --schema-definition <file>, --dry-run, --force (overwrite an occupied path with a new lineage)

document update <id>

diffs -f <file> (.md or .json only, not .pdf) against the current content by block id and publishes only changed blocks; the metadata flags of document create, --delete-blocks <ids>, -k. Takes over the address of a redirect or republish. --parent is accepted but has no effect.

document delete <id>

publishes a tombstone Ref

document fork <source> <destination>

a new path on the source's history

document move <source> <destination>

a version Ref at the destination and a redirect at the source

document redirect <id> --to <target> [--republish]

a redirect Ref; with --republish the target's content shows at this path

document changes <id>

the change history (ListChanges)

document stats <id>

interaction counts

document validate <id> [--content]

checks the document against its effective attributes schema; exit 1 on violations

document cid <cid>

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

comment get <id>

one comment

comment list <targetId>

comments on a document

comment create <targetId> --body <text> | --file <path> [--reply <commentId>]

a comment; the body is markdown. A #blockId fragment on the target makes a block comment.

comment edit <commentId> --body | --file

replaces the comment, keeping its thread position

comment delete <commentId>

a tombstone

comment discussions <targetId> [-c <id>]

threaded discussions

capability, contact, account

Command

What it does

capability create --delegate <uid> --role WRITER|AGENT [--path <p>] [--label <text>]

signs and publishes a capability from your key to another account, optionally scoped to a path

contact create --subject <uid> --name <name>

a contact: a named reference to another account

contact delete <recordId|cid>

a tombstone

contact list [uid] [--account] [--subject]

contacts by or about an account

account get <uid>, account list, account contacts <uid>

account lookups

account profile set --name <n> [--icon ipfs://…] [--description <d>] [-a <uid>]

publishes a profile blob; --avatar is another name for --icon; with -a another account's profile from a delegated key

account capabilities <id>

who may write to a space or path

key

Command

What it does

key generate [-n main] [-w 12|24] [--passphrase] [--show-mnemonic]

a new key in the OS keyring; a name may use letters, digits, hyphens and underscores only

key import <mnemonic> [-n imported] [--passphrase]

a key from a BIP-39 phrase

key list

every key the CLI finds in the vault and the keyring, with its source

key show [nameOrId], key default [nameOrId], key rename <old> <new>, key remove <nameOrId> [-f]

keyring keys only for rename and remove; the CLI never modifies a vault

key derive <mnemonic> [--passphrase]

prints the account id without storing anything

key export [nameOrId] [-o <path>] [--password] [-f]

writes a .hmkey.json (mode 0600) that the app, the vault and SEED_CLI_KEYFILE accept

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

space export <space|self> -d <dir>

writes every document of a space as lossless markdown, home document as index.md, /a/b as a/b.md, a defined schema as a/b.schema.json

space import <space|self> -d <dir> [--dry-run] [--check]

publishes the directory, diffing existing documents by block id and detecting moves; --check validates every file against its schema first and publishes nothing on a violation. The signing key must own the space.

space export <space|self> -d <dir> --assets

also downloads every file the documents link into <dir>/assets/ and links it relatively

space archive <space|self> -o <file.zip> [-f, --format markdown|blobs] [--no-comments]

saves the whole space in one zip. markdown (the default) is the space export folder with its assets, readable anywhere. blobs is every signed blob of the space (Refs, changes, capabilities, comments, file blocks), byte for byte, each checked against its CID

space restore <file.zip> [--into <space|self>] [-d <dir>] [--dry-run]

a blob archive is published as is to --server, with its signatures and history intact. A markdown archive is imported into --into (default self) like space import, as new changes signed by your key

space dev -d <dir> [--api http://localhost:58004] [--daemon http://localhost:58001] [--interval 2000] [--no-push] [--no-watch] [--keep-stale]

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

blob get <cid>

prints a blob as DAG-JSON

blob validate -f <file> [-s <ref>]

checks a dag-json value against a schema (a file, ipfs://<cid>, a library name, or a type document's hm:// URL)

blob create -f <file> [-s <ref>] [--no-link] [--force] [--dry-run]

publishes a value as a DAG-CBOR blob, validated and linked to its schema

blob sign -f <file> [-s <ref>] [-t <type>] [--ts <ms>] [-k] [--force] [--dry-run]

adds the signed envelope (signer, ts, sig) and publishes

blob verify <cid> [-s <ref>]

checks the signature and the schema

schema get <ref> [--resolve]

a schema with its CID; --resolve follows references and merges extensions

schema validate <ref>

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

search <query> [-a <uid>] [-t keyword|semantic|hybrid] [-c <n>] [-l <n>] [--titles-only]

full-text search; -q prints id, block, type and title per line

query <space|*> [-p <path>] [-m Children|AllDescendants] [-l <n>] [--sort <term>] [--reverse]

a directory listing

query <space|*> -w '<explore query>' [--filter <json>] [--sort-by <key>] [--page-token <t>]

documents by attribute, anywhere with *; see Query grammar

children <space> [-p <path>]

shorthand for a Children query

attributes [space] [--parent <path>] [--recursive] [--values <key>] [--kind string|int|bool] [--prefix <text>]

which attribute keys documents use and the values a key takes

citations <id>

documents that link here

activity [-l <n>] [-t <token>] [--authors <uids>] [--resource <id>]

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.

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

Unsubscribe anytime