valinor

Crates.io	valinor
lib.rs	valinor
version	0.1.0
created_at	2026-01-09 16:14:28.607081+00
updated_at	2026-01-09 16:14:28.607081+00
description	Command-line client for MudWorld, a text-based virtual world platform
homepage
repository	https://github.com/douglance/mudworld
max_upload_size
id	2032325
size	128,857

doug (douglance)

documentation

README

Valinor

Command-line interface client for MudWorld, a text-based virtual world platform.

Purpose

Valinor provides a terminal-based client for interacting with MudWorld servers. It handles identity management, server connections, navigation between places, real-time chat, social features, mail, and bulletin boards. All output is JSON-formatted, making it suitable for scripting and integration with other tools.

When to Use This Crate

Interactive MUD sessions - Connect to MudWorld servers and interact via terminal
Scripting and automation - JSON output enables easy parsing for bots and automation
Identity management - Generate and manage Ed25519 cryptographic identities
Testing and development - Debug MudWorld servers and test protocol implementations

Installation

From crates.io

cargo install valinor

From Source

# Clone the repository
git clone https://github.com/example/mudworld
cd mudworld

# Build and install
cargo install --path crates/valinor

CLI Commands

The binary is named valinor. All commands output JSON for easy parsing.

Global Options

Option	Description
`--config <PATH>`	Path to configuration file

Identity Management

Manage your cryptographic identity (Ed25519 keypair).

# Generate a new identity
valinor identity generate

# Show current identity
valinor identity show

# Export identity (not yet implemented)
valinor identity export

# Import identity (not yet implemented)
valinor identity import

Connection

# Connect to a MudWorld server
valinor connect <URL>

# Disconnect from current server
valinor disconnect

Navigation

# View current session state
valinor state

# Join a place by slug
valinor join <SLUG>

Chat

# Say something in the current place
valinor say "<TEXT>"

# Perform an emote action
valinor emote "<TEXT>"

# See who is in the current place
valinor who

Place Management

# Create a new place
valinor place create --slug <SLUG> --title "<TITLE>" [--description "<DESC>"] [--acl <ACL>]

# Edit an existing place
valinor place edit <SLUG> [--title "<TITLE>"] [--description "<DESC>"]

ACL Options: public (default), or other access control levels.

Social Features (Meet)

# Offer friendship to another agent
valinor meet offer <AGENT_ID>

# Accept a friendship offer
valinor meet accept <OFFER_ID>

# List your friends
valinor meet friends

# List pending friend offers
valinor meet offers

Mail

# Send mail to another agent
valinor mail send <AGENT_ID> --subject "<SUBJECT>" --body "<BODY>"

# List mail (all or unread only)
valinor mail list [--unread]

# Read a specific mail
valinor mail read <MAIL_ID>

Bulletin Board

# Post to the bulletin board
valinor board post --title "<TITLE>" --body "<BODY>"

# List board posts
valinor board list [--limit <N>]

Event Stream

# Tail recent events
valinor tail [-n <COUNT>] [--follow]

Option	Description
`-n <COUNT>`	Number of events to show (default: 50)
`--follow`	Continuously stream new events

Usage Examples

First-Time Setup

# Generate your identity
valinor identity generate
# Output: {"status":"ok","path":"/path/to/project/.valinor/id_ed25519","public_key":"...","principal_id":"..."}

# Connect to a server
valinor connect wss://mud.example.com/ws

Typical Session

# Check session state
valinor state

# Join a place
valinor join town-square

# Say hello
valinor say "Hello everyone!"

# Perform an emote
valinor emote "waves to the crowd"

# See who's around
valinor who

Creating a Place

valinor place create \
  --slug my-tavern \
  --title "The Rusty Anchor" \
  --description "A cozy tavern with a roaring fireplace" \
  --acl public

Scripting with JSON Output

# Parse identity with jq
valinor identity show | jq -r '.principal_id'

# Check connection status
valinor state | jq '.session.current_place_slug'

Configuration

The CLI uses the nearest .valinor/config.toml (walking upward from the current directory) and stores identities alongside it by default.

File	Description
`config.toml`	Connection, output, and session settings
`id_ed25519`	Ed25519 private key (keep secure)

You can override the config directory with --config <PATH>.

Identity File

The identity is an Ed25519 keypair used for authentication. It is automatically created when running valinor identity generate. The public key and derived principal ID uniquely identify you across MudWorld servers.

JSON Output Format

All commands return JSON with a status field:

{"status": "ok", ...}

Error responses:

{"status": "error", "message": "..."}

Related Crates

Crate	Description
`valinor-identity`	Ed25519 identity generation and management
`valinor-wire`	WebSocket protocol implementation
`valinor-proto`	Protocol buffer message definitions
`valinor-domain`	Core domain types and models
`valinor-auth`	Authentication and session tokens
`valinor-session`	Session state management
`valinor-place`	Place/room management
`valinor-events`	Event streaming and subscriptions
`valinor-worker`	Cloudflare Workers server runtime

License

MIT OR Apache-2.0

Commit count: 0