Linux (package manager)

Debian/Ubuntu

sudo apt-get install grpcurl

Fedora/RHEL

sudo dnf install grpcurl

Arch

sudo pacman -S grpcurl

Or download binary from: https://github.com/fullstorydev/grpcurl/releases


## Server Endpoints

Seed gRPC server runs on:

- **Dev**: `localhost:58002`
- **Production**: `localhost:56002`

Check which is available first.

## Hypermedia IRI Format

**Document IRI**: `hm://<account>/<path>?v=<version>#<block>&l`

- Only `<account>` is required (e.g., `z6Mk...`)
- `<path>`: Optional document path
- `?v=<version>`: Optional specific version
- `#<block>`: Optional block ID
- `&l`: Optional latest version flag

**Comment IRI**: `hm://<author>/<tsid>`

- `<author>`: Account identifier
- `<tsid>`: Timestamp-based comment ID

## Workflow

### 1. Check Server

```bash
grpcurl -plaintext localhost:58002 list  # Try dev first
grpcurl -plaintext localhost:56002 list  # Then production

2. Initial API Discovery (Once per Session)

Use reflection to discover the API structure for new commands you don't know about. Important: Once you've discovered a service/method structure, you can reause it without doing reflection again. Assume the server does not change. However if subsequent requests fail (read the error message) and they fail because of structure, then you may do reflection again.

# List all services
grpcurl -plaintext <host:port> list

# Describe a service to see its methods
grpcurl -plaintext <host:port> describe <service.name>

# Describe a method to see its signature
grpcurl -plaintext <host:port> describe <service.name.MethodName>

# Describe message structure to see required fields
grpcurl -plaintext <host:port> describe <message.type>

3. Parse User Intent

Extract what Seed operation is needed
If the request is write/update/delete, refuse and route to seed-cli (do not call any gRPC method)
Parse any IRIs to get account, path, version, etc.
If needed service/method is unknown, use reflection to discover it (once)
Determine if this requires single or multiple calls

4. Make RPC Calls

Single operation:

grpcurl -plaintext -d '{"field": "value"}' <host:port> <service/Method>

Compound operations (multiple dependent calls):

# Get data from first call
RESULT=$(grpcurl -plaintext -d '{...}' <host:port> <service1/Method1>)

# Extract needed field using jq
VALUE=$(echo "$RESULT" | jq -r '.fieldName')

# Use in next call
grpcurl -plaintext -d "{\"field\": \"$VALUE\"}" <host:port> <service2/Method2>

### 5. Download media referenced by IPFS

When a document references a media file (audio/video/image/document), it will often be an IPFS URI like:

`ipfs://<cid>`

To download the bytes, use the **local HTTP gateway** (this is not gRPC):

- URL format: `http://localhost:<httpport>/ipfs/<cid>`
- Port mapping: `httpport = grpcport - 1`
	- Dev: gRPC `58002` → HTTP `58001`
	- Production: gRPC `56002` → HTTP `56001`

Example:

`curl -L "http://localhost:58001/ipfs/<cid>" --output /tmp/downloaded-file`
select the extension according to the media type

IRI Parsing

Document IRI hm://<account>/<path>?v=<version>#<block>&l:

account: Text after hm:// until first /, ?, #, or &
path: Text after first / until ?, #, or & (empty string if absent)
version: Value after ?v= (if present)
block: Value after # (if present)
latest: Check for &l flag

Comment IRI hm://<author>/<tsid>:

author: Text after hm:// until /
tsid: Text after /

CLI Export

For exporting documents as markdown (with frontmatter and block IDs), use the Seed CLI instead of gRPC. The CLI's document get command outputs round-trip-compatible markdown by default:

# Install or update seed-cli (once per session, npm package: @seed-hypermedia/cli)
if ! command -v seed-cli &>/dev/null; then
  npm install -g @seed-hypermedia/cli
fi
LOCAL_V=$(seed-cli --version 2>/dev/null)
LATEST_V=$(npm view @seed-hypermedia/cli version 2>/dev/null)
if [ -n "$LATEST_V" ] && [ "$LOCAL_V" != "$LATEST_V" ]; then
  npm install -g @seed-hypermedia/cli@latest
fi

# Default output: markdown with frontmatter and block IDs
seed-cli document get hm://z6Mk.../my-doc

# Write to file
seed-cli document get hm://z6Mk.../my-doc -o doc.md

# Structured output (JSON/YAML)
seed-cli document get hm://z6Mk.../my-doc --json

For piping exported markdown back into write operations, see the seed-cli skill.

Key Rules

Read-only only - This skill must never call write/update/delete endpoints. Refuse any request that would modify Seed data and route to seed-cli.
Discover once per session - Use reflection to learn API structure, then reuse that knowledge. The server won't likely change during the session.
Parse IRIs carefully - Extract all components according to format above
Omit optional fields - If IRI component is absent, don't send it (not even empty string)
Check signatures before first use - Use describe to understand method parameters
Chain efficiently - For compound operations, minimize calls while getting needed data
Handle pagination - Check for page_size/page_token fields, default to 50-100 for page_size
Summarize large responses - Show key data for responses >10KB
Prefer account names over account IDs - Do not surface raw account IDs to the user when referring to standalone accounts/authors (e.g., in “Author”, “Account”, “Owner” fields). Instead, resolve a human-friendly account name using the server’s account lookup/search RPC (discover it via reflection if needed). Exception: when displaying a Document IRI or Comment IRI (e.g., hm://<account>/...), keep the <account> portion unchanged because it is part of the URL; if helpful, present the resolved display name separately alongside the IRI.

Document Model Reference

For understanding the block tree structure, block types, annotations, and IRI format returned by gRPC document responses, see ./references/seed-document-format.md.

Response Handling

Extract key Seed metadata (names, authors, timestamps)
Explain errors in user-friendly terms
If method doesn't exist, use reflection to find alternatives

seed-grpc

Seed gRPC Skill

Prerequisites

More from seed-hypermedia/skills

seed-cli