Seed CLI

The Seed CLI is a command-line interface for interacting with the Seed Hypermedia network. It allows you to fetch documents, search content, manage accounts, and perform various operations on the hypermedia network.

Seed servers are open source and self-hostable servers running on the peer-to-peer Hypermedia network. You can use the CLI to interact with any Seed server using its API.

Browse the open source Seed Hypermedia repository here: https://github.com/seed-hypermedia/seed

Learn more at https://seed.hyper.media

Download the Seed desktop app: https://download.seed.hyper.media

Installation

You can run the Seed CLI directly using npx without installation:

npx @seed-hypermedia/cli@latest

If you want to install globally, you can install via npm:

npm i -g @seed-hypermedia/cli

Now you have access to the seed CLI:

seed -—help

Global Options

-V, --version: Output the version number

-s, --server <url>: Server URL (default: "https://hyper.media")

--json: JSON output (default)

--yaml: YAML output

--pretty: Pretty formatted output

-q, --quiet: Minimal output

-h, --help: Display help for command

Commands

Document Operations

get <id> - Fetch a document, comment, or entity

Fetch content by Hypermedia ID.

Options:

-m, --metadata: Fetch metadata only

--md: Output as markdown

--frontmatter: Include YAML frontmatter (with --md)

-r, --resolve: Resolve embeds, mentions, and queries (with --md)

-q, --quiet: Output minimal info

Example:

npx -y @seed-hypermedia/cli get --md "hm://HYPERMEDIA_URL_HERE"

cid <cid> - Fetch raw IPFS block by CID

Retrieve raw IPFS content by Content Identifier.

stats <id> - Get interaction statistics for a document

Get metrics and statistics for a specific document.

Search and Query

search <query> - Search for documents

Search across the hypermedia network.

Options:

-a, --account <uid>: Limit search to specific account

-q, --quiet: Output IDs and titles only

query <space> - List documents in a space

Query documents within a specific space.

Options:

-p, --path <path>: Path prefix

-m, --mode <mode>: Query mode: Children or AllDescendants (default: "Children")

-l, --limit <n>: Limit results

--sort <term>: Sort by: Path, Title, CreateTime, UpdateTime, DisplayTime

--reverse: Reverse sort order

-q, --quiet: Output IDs and names only

children <space> - List child documents

Shorthand for query --mode Children.

Options:

-p, --path <path>: Path prefix

-l, --limit <n>: Limit results

-q, --quiet: Output IDs and names only

citations <id> - List documents citing this resource

Find documents that reference or cite a specific resource.

Options:

-q, --quiet: Output source IDs only

Account Management

account <uid> - Get account information

Retrieve information about a specific account.

Options:

-q, --quiet: Output ID only

accounts - List all known accounts

List all accounts known to the system.

Options:

-q, --quiet: Output IDs and names only

contacts <uid> - List contacts for an account

Get the contact list for a specific account.

Options:

-q, --quiet: Output names only

Comments and Discussions

comments <targetId> - List comments on a document

Get all comments for a specific document.

Options:

-q, --quiet: Output IDs and authors only

discussions <targetId> - List threaded discussions on a document

Get threaded discussion view for a document.

Options:

-c, --comment <id>: Filter to specific thread

-q, --quiet: Minimal output

comment <id> - Get a single comment by ID

Retrieve a specific comment.

Access Control

capabilities <id> - List access control capabilities

View access control permissions for a resource.

Activity and History

activity - List activity events

View recent activity across the network.

Options:

-l, --limit <n>: Page size

-t, --token <token>: Page token for pagination

--authors <uids>: Filter by author UIDs (comma-separated)

--resource <id>: Filter by resource

-q, --quiet: Output summary only

changes <targetId> - List document change history

View the change history for a specific document.

Options:

-q, --quiet: Output CIDs and authors only

Key Management

key - Manage signing keys

Manage cryptographic keys for signing and authentication.

Subcommands:

key generate - Generate a new signing key

Generate a new signing key from a BIP-39 mnemonic.

Options:

-n, --name <name>: Name for the key (default: "default")

-w, --words <count>: Mnemonic word count: 12 or 24 (default: "12")

--passphrase <pass>: Optional passphrase for key derivation

--show-mnemonic: Display the mnemonic (DANGER: write it down securely)

key import <mnemonic> - Import a key from existing mnemonic

Import a signing key from an existing BIP-39 mnemonic phrase.

Options:

-n, --name <name>: Name for the key (default: "imported")

--passphrase <pass>: Optional passphrase for key derivation

key list - List stored signing keys

Display all stored signing keys.

key show [nameOrId] - Show key information

Display information about a specific key or the default key.

Options:

--show-mnemonic: Display the mnemonic (DANGER)

key remove <nameOrId> - Remove a stored key

Permanently delete a stored signing key.

Options:

-f, --force: Skip confirmation prompt

key default [nameOrId] - Set or show default signing key

Set the default key for signing operations, or show the current default.

key derive <mnemonic> - Derive account ID from mnemonic

Derive and display the account ID from a mnemonic without storing it.

Options:

--passphrase <pass>: Optional passphrase for key derivation

Configuration

config - Manage CLI configuration

Configure CLI settings.

Options:

--server <url>: Set default server URL

--show: Show current configuration

Common Use Cases

Reading a Document as Markdown

npx -y @seed-hypermedia/cli get --md "hm://document-id-here"

Reading with Full Context Resolution

npx -y @seed-hypermedia/cli get --md --resolve --frontmatter "hm://document-id-here"

Searching for Content

npx -y @seed-hypermedia/cli search "your search terms"

Listing Documents in a Space

npx -y @seed-hypermedia/cli query "space-id" --sort UpdateTime --reverse

Getting Account Information

npx -y @seed-hypermedia/cli account "account-uid"

Viewing Comments

npx -y @seed-hypermedia/cli comments "document-id"

Managing Keys

# Generate a new key and show the mnemonic
npx -y @seed-hypermedia/cli key generate --name mykey --show-mnemonic

# Import an existing mnemonic
npx -y @seed-hypermedia/cli key import -n imported "word1 word2 ... word12"

# List all keys
npx -y @seed-hypermedia/cli key list

# Derive account ID without storing
npx -y @seed-hypermedia/cli key derive "word1 word2 ... word12"

Output Formats

The CLI supports multiple output formats:

JSON (default): Machine-readable structured data

YAML: Human-readable structured data (--yaml)

Pretty: Formatted output (--pretty)

Markdown: For documents (--md with get command)

Quiet: Minimal output (--quiet)

Server Configuration

By default, the CLI connects to https://hyper.media. You can:

Use a different server for a single command: -s, --server <url>

Set a default server: npx -y @seed-hypermedia/cli config --server <url>

View current configuration: npx -y @seed-hypermedia/cli config --show