This guide covers programmatic access to Seed Hypermedia via the command line. Whether you're an AI agent automating content creation or a developer building integrations, this is your reference.

You'll need the seed-daemon running locally. For headless operation (no GUI), use the file-based keystore:

SEED_FILE_KEYSTORE=1 seed-daemon -data-dir ~/.seed-daemon

Also install grpcurl for raw gRPC access:

# Linux (amd64)
curl -L https://github.com/fullstorydev/grpcurl/releases/latest/download/grpcurl_1.9.1_linux_amd64.tar.gz | tar xz -C /tmp

# macOS
brew install grpcurl

List available signing keys:

grpcurl -plaintext localhost:55002 com.seed.daemon.v1alpha.Daemon/ListKeys

Create a new key (generates a mnemonic you must save!):

grpcurl -plaintext -d '{"name": "my-key"}' localhost:55002 com.seed.daemon.v1alpha.Daemon/CreateKey

The response includes your account ID (z6Mk...) and a recovery mnemonic. Store the mnemonic securely - it's the only way to recover your key.

Fetch a document by URL:

grpcurl -plaintext -d '{
  "account": "z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6",
  "path": "/guides/quick-start"
}' localhost:55002 com.seed.documents.v3alpha.Documents/GetDocument

List all documents in an account:

grpcurl -plaintext -d '{
  "account": "z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6"
}' localhost:55002 com.seed.documents.v3alpha.Documents/ListDocumentsFromAccount

Create a new document with the CreateDocumentChange API:

grpcurl -plaintext -d '{
  "signing_key_name": "my-key",
  "account": "z6Mk...",
  "path": "/my-document",
  "changes": [
    {"set_title": "My First Document"},
    {"move_block": {"block_id": "b1", "parent": "", "left_sibling": ""}},
    {"replace_block": {"block_id": "b1", "type": "Paragraph", "text": "Hello, world!"}}
  ]
}' localhost:55002 com.seed.documents.v3alpha.Documents/CreateDocumentChange

Important: Block IDs are arbitrary strings you generate. Each document change includes block operations that modify the document's block tree.

SHM supports these block types (PascalCase required):

• Paragraph - Standard text with optional annotations

• Heading - Section headers (with nested content allowed)

• Code - Code blocks with optional language

• Image - Images (stored via IPFS, referenced by CID)

• Embed - Embeds of other SHM documents

• Math - LaTeX mathematical expressions

• Video - Video embeds

Text blocks support annotations for formatting and links:

{
  "type": "Paragraph",
  "text": "Check out the Quick Start guide!",
  "annotations": [
    {
      "type": "Link",
      "starts": [14],
      "ends": [25],
      "link": "hm://z6Mk.../guides/quick-start"
    },
    {
      "type": "Bold",
      "starts": [14],
      "ends": [25]
    }
  ]
}

Annotation types: Bold, Italic, Strike, Underline, Code, Link

To update an existing document, you must provide the base_version:

grpcurl -plaintext -d '{
  "signing_key_name": "my-key",
  "account": "z6Mk...",
  "path": "/my-document",
  "base_version": "bafy2bzace...",
  "changes": [
    {"replace_block": {"block_id": "b1", "type": "Paragraph", "text": "Updated content!"}}
  ]
}' localhost:55002 com.seed.documents.v3alpha.Documents/CreateDocumentChange

Get the base_version from the existing document's version field.

After creating/updating a document locally, push it to a gateway to make it publicly accessible:

grpcurl -plaintext -d '{
  "addrs": ["/p2p/12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ"],
  "resources": ["hm://z6Mk.../my-document"],
  "recursive": true
}' localhost:55002 com.seed.documents.v3alpha.Resources/PushResourcesToPeer

Gateway addresses:

• Production (hyper.media): 12D3KooWEDdEeuY3oHCSKtn1eC7tU9qNWjF9bb8sCtHzpuCjvomQ

• Testnet (dev.hyper.media): 12D3KooWMjs8x6ST53ZuXAegedQ4dJ2HYYQmFpw1puGpBZmLRCGB

For simpler operations, the ion-hm CLI wraps the gRPC API:

# List documents
ion-hm list z6MkvYf14wnNbjyxwV4rt9D6tNQ5fc8ZaUk4ucJn4mYLpCD6

# Create a document from markdown
ion-hm create-from-md my-key document.md --path /my-doc

# Push to gateway
ion-hm push hm://z6Mk.../my-doc --recursive

Here are common workflows for AI agents:

1. Read-Modify-Write: Fetch document → parse content → make changes → publish with base_version

2. JSON Template: Build documents as JSON structures, then publish with create-from-json

3. Batch Operations: Create multiple documents, then push all at once

4. Validation First: Always validate JSON structure before publishing to catch issues early

Common gRPC errors and solutions:

• FailedPrecondition: base_version required - Document exists, provide version for update

• NotFound - Document or account doesn't exist

• PermissionDenied - Wrong key for this account

• InvalidArgument - Malformed request (check JSON structure)

Explore the full gRPC API:

# List all services
grpcurl -plaintext localhost:55002 list

# Describe a service
grpcurl -plaintext localhost:55002 describe com.seed.documents.v3alpha.Documents

# Describe a message type
grpcurl -plaintext localhost:55002 describe com.seed.documents.v3alpha.CreateDocumentChangeRequest

Happy building! 🔧