Lib.rs

› Network programming
#virtual-world #chat #multi-player #mud

app valinor

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

by MudWorld Contributors. Owned by douglance.

1 unstable release

Uses new Rust 2024

0.1.0 Jan 9, 2026

#2 in #mud

MIT/Apache

115KB
2K SLoC

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":"/https/lib.rs/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": "..."}
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

Dependencies

~18–42MB
~457K SLoC