This manual covers the full command surface of the current alpha build. You can read it top to bottom, or jump to the Command reference when you just need syntax. Commands are shown as you type them; angle brackets like <name> mark values you fill in, and [brackets] mark optional parts.

What is Kunuleco

Kunuleco is a platform for creating private digital spaces you actually own. The name comes from Esperanto: kunuleco means "fellowship" — the experience of being together with people who matter to you. It isn't a social network; it's infrastructure for genuine connection — small groups, trusted circles, real conversations.

Your space doesn't live on someone else's server. It runs on your machine, as a node, under your control. Four ideas hold the whole system together:

Two ways to connect

Client-only commands (network view, updates, accessibility, wizards) are listed under Urchin client commands and exist only in the graphical app.

Command mode & chat mode

The Urchin client has two input modes:

• Command mode — everything you type is a verb (look, say hello, create ~room garden).
• Chat mode — bare text goes to the channel you're in; prefix a command with / to run it (/look).

Switch with /cmd and /chat, and set your default with /defaultmode. Over SSH there are no modes — you're always typing commands directly.

Create your identity

Your identity is the first thing you make, and it belongs to you. It's a cryptographic keypair stored on your machine, protected by a password only you know.

In the Urchin client

On the welcome screen, enter a username and choose Create Identity. You'll set a username, password, and theme. If the node already has members, you'll be sent to the Sponsor step instead (see below). When you're done you land on a success screen offering to create a room, join with an invite code, or go to your HOME.

Over SSH / first node

The very first account on a brand-new node is created freely. After that, account creation is sponsored. The raw protocol commands are:

USER <username>          begin login
PASS <password>          authenticate
ADDUSER <username> <password>   create an account

Sponsorship — how new accounts join

Once a node has members, a new person can't just create an account: an existing user must authorize the registration. In the client this is the "Sponsor required" panel — the newcomer supplies their desired credentials plus a sponsor's username and password, and the sponsor's authorization creates the account. This keeps a node's membership intentional rather than open to the world.

The guided tour

The first time you log in through the Urchin client, the node introduces itself and walks you through the essentials. It opens in the node's own voice:

From there it has you run whoami (to meet your identity) and transport (to see how you're connected), shows your starting commands, explains how to make a room and invite someone, points out accessibility and input modes, and then closes:

The tour ends with a small ritual — you type /chat to step out of learning and into inhabiting the space. You can type skip at any point to jump to the closing. The tour runs once per identity.

Your first commands

These are the verbs the node teaches first — enough to look around, move, talk, and build.

Concept · Your identity

Your identity in Kunuleco is self-sovereign and built in three layers:

Under the hood your identity has three documents you'll occasionally see named:

• AIRO — your private credential blob, encrypted on disk (this is "your identity").
• PIRO — your public, shareable identity document: how peers learn to reach you across transports.
• NIRO — the node's own identity.

Across the social layer your canonical key is written as a DID (e.g. did:key:z6Mk…), and it is treated as the single source of truth about who someone is — names can change, the key cannot. Kunuleco uses KERI-style key rotation: each key event commits in advance to your next key and is recorded in an append-only chain, so a compromised key can be rotated out without losing your identity. See Back up your identity for the practical side.

Concept · Spaces & Halls

Kunuleco spaces nest from broad to specific:

• HOME — your personal root space, created at first login. You are always its Steward.
• Halls — community hubs you found for a group. Each Hall (and your HOME) is divided into three zones.
• Zones — access tiers within a hub: Public (open to visitors), Common (members), and Private (stewards). Crossing into a zone is gated by your Standing.
• Rooms — the actual places you gather and talk, living inside a zone. Connected by exits (one-way or two-way).

You move with go <exit>, look with look, and return HOME with home. Found a community space with found hall <name> — it builds the hub, its three zones, and starter rooms (welcome / general / governance), and makes you the Steward.

Concept · Standing & trust

Standing is your trust level within a particular space. It rises from visitor to steward, and each tier unlocks deeper zones and more authority:

Check yours with standing. A Steward grants a tier with standing <user> <tier>. Entry to a gated Hall flows through a knock queue: newcomers knock (handled automatically), the Steward reviews with knocks and uses accept / reject, and existing members can vouch for someone to speed them through.

Concept · Presence

Presence is being somewhere, with other people, right now. It has three properties: a location (which space you're in), visibility (others can see you're here), and it's ephemeral (it's gone when you disconnect).

Crucially, presence is not the same as capability. If someone can reach your node and join your room, they're present — but what they can actually do (open a capsule, post to a board) is a separate, capability-gated decision. You talk to a presence with say (the room), chat <channel> (a named presence), or tell <person> (privately — a 1-on-1 message saved to a persistent history).

Concept · Capsules & capabilities

A capsule is a capability-gated container. It holds objects and can expose services — methods other people can call. Capsules are the unit of sharing: you can give someone access to one capsule without exposing anything else.

Access works by capability, not by membership list. You grant an identity specific capabilities (read, write, …) on a capsule, and revoke them later. A capsule can also carry services built from templates (echo, ping, inventory) which remote peers invoke over the network. Capsules are exported as capsule:<name>:<service_type> when shared.

Concept · Friends & petnames new

The social layer remembers the people you meet, so your contacts survive restarts instead of vanishing each session.

• Peer registry — a private, persistent record of everyone you've encountered, keyed by their DID. Each contact starts as discovered and can become a contact or be blocked.
• Petnames — your own private aliases for people. A petname is bound to a specific identity (by DID), so an impostor reusing someone's display name can't inherit the alias. Set with petname <identity> <name>. Once set, tell and chat recognize it.
• Friends — promote someone you've met to a contact with friend. List them with contacts, inspect one with finger, and check who's reachable right now with friends online.
• Persistent chat & outbox — tell <friend> <message> (also spelled whisper or @chat) sends a one-to-one message and saves it to a history that survives restarts. With no message, tell <friend> shows your recent history together. If the friend is offline, the message waits in your outbox and you can outbox flush to retry once they're back.

Concept · Connections & transports

Kunuleco speaks over several transports and tries them in order, so a blocked path doesn't cut you off. The messaging layer on top (called CapTP) is the same regardless of which transport carries it.

A short code (like tiger-castle-7) is a memorable lookup key — behind it sits your real connection info (identity plus mDNS / Veilid / Tor endpoints) and a one-time token. You hand someone a code; they join it. See how you're connected with transport and which daemons are running with @node_processes.

How do I… make a room and invite someone?

1Create the room.

create ~room garden --desc A quiet place to talk

2Share it so others can reach it (this also opens a presence/chat channel):

share room garden

3Create an invite. You'll get a short code to pass along:

invite garden -short
→ tiger-castle-7

4Your guest joins with the code (or your canonical name):

join tiger-castle-7

To wire rooms together, use exits <room> add <name> <target> (add --oneway for a one-way passage).

How do I… found a Hall and manage entry?

found hall riverside

In the Urchin client, /found-wiz runs this as a guided ritual (name → description → atmosphere → threshold → optional first room). Either way, it creates the Hall hub, its Public/Common/Private zones, and welcome / general / governance rooms. You're the Steward. Then shape it:

describe hall What brings us together is shared music.
set hall atmosphere Playful
set hall threshold knock

With knock, arrivals queue for your approval:

How do I… add friends and keep a chat history? new

Once you've met someone (you've seen them connect or discovered them), add them and give them a petname in one step:

@friend add alex#429754 my-bandmate

That befriends alex#429754 and sets the petname my-bandmate. From then on:

contacts                       list your friends
friends online                see who's reachable right now
finger my-bandmate             full detail on one contact
tell my-bandmate Hey, you around?    one-to-one, saved to history
tell my-bandmate               show recent history with them

(tell, whisper, and @chat are the same command — use whichever you prefer.)

If they were offline when you sent, the message waits in your outbox:

outbox            see what's queued
outbox flush      retry delivery now

Manage aliases directly with petname <identity> <name>, list them with petnames, and remove one with petname <name> --clear. To stop following someone, unfriend <identity>; to cut them off entirely, block <identity>.

How do I… share a capsule or board?

Capsule. Create one, then share it and grant capabilities:

create ~capsule notes
share capsule notes
grant notes alex#429754 read,write

Revoke with revoke notes alex#429754. See who has what with list grants notes.

Board. Bulletin boards are threaded and persistent:

@board_create music Music Chat
post Practice moved to Friday --board music
posts --board music
reply 3 Works for me
share board music --post        share read+post (omit --post for read-only)

How do I… share media?

media upload ~/pictures/poster.png --caption Friday's show
media list
media share <id> lobby

Uploads (PNG / JPEG / GIF / WebP) go to IPFS and are shared into a presence as a clickable tag; in the Urchin client they open in a media popup. Remove your own with media delete <id>.

How do I… back up or move my identity?

Because there's no password reset, an encrypted export is your safety net and the way to move to a new machine.

export-identity ~/kunuleco-backup.id <base64_passphrase>
import-identity ~/kunuleco-backup.id <base64_passphrase> --overwrite

How do I… check my connection & troubleshoot?

In the Urchin client, /network shows a live network view and /check-updates / /update handle upgrades. Updates are cryptographically verified: the app checks each release against a signed manifest before it applies anything, and a fresh install works even offline because the app carries that signed manifest with it. The app you downloaded is the trust anchor, and nothing installs or updates without a valid signature.

Command reference

Case-insensitive. help <verb> prints detailed help for any command. Verbs beginning with @ are lower-level or diagnostic; their plain-word equivalents (above them here) are the everyday way in.

Account & session

Navigation & looking

Talking

Friends & petnames new

Building · rooms, Halls, objects

Capsules, capabilities & services

Boards

Media

Identity

Invites & joining

Advanced & diagnostics advanced

Shown by help debug. Not needed for everyday use — handy when verifying connectivity or reporting a bug.

Urchin client commands client only

These exist only in the graphical client (prefix with / in chat mode). Over SSH they don't apply.

Glossary