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 your active channel, and the whole line is the message. Prefix a command with / to run it (/look), or address a different channel by its ! sigil: !garden hello.

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

Addressing never creates or switches: a channel is made only by the explicit act (create ~presence <name>), addressing an unknown one is an error, and sending never changes which channel is active.

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, and it becomes the node's owner. The node also has an account of its own, the node user, which signs the owner's grants once at that moment and can never be signed into. 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: a sponsor must authorize the registration, and a sponsor is someone who holds the right to create accounts (create_user). The owner holds it from the start and can pass it on. Not every member has it. 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), transport (to see how you're connected), and look (to see where you are), explains the two input modes and the menus at the top, shows how to make a space and bring people in, and then closes:

The tour closes by handing you help — your commands are yours to explore. 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.

When your node connects to another, each side proves who it is with a signed hello, and what it proves is an AID, a KERI identifier. A name can change and anyone can claim one, so what must hold on to a person, such as a block or an admission to a room, keys on the AID the connection proved. KERI records each key event in an append-only chain that commits in advance to the next key, which is what will let a key be rotated. There is no command to rotate a key yet. Your older did:key:z6Mk… identifier still appears in places such as your peer registry. 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 (your active channel — or a named one explicitly: chat !garden hello), or tell <person> (privately — a 1-on-1 message saved to a persistent history).

A person whose identity can't be derived renders as UNIDENTIFIED. The word is deliberate: it means we cannot say who this is, and absence of identity is never dressed up as somebody.

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. A block covers the person, not one key. It holds on every record for the AID they proved, over any transport and after a reconnect.
• 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 recognizes 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. When it connects to a peer it tries them at the same time and keeps the first that connects, 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.

In the Urchin client, the status bar names the link's state exactly. Encrypted (certified) means the channel is encrypted and the node's certificate matches the one your client holds, either your own node on this computer or a remote node whose trust bundle you imported. Encrypted (uncertified) means the channel is encrypted but the node's identity is not verified yet. The pair is deliberate, because the second is the weaker claim, and the bar never shows a plain "connected" where identity is unproven.

Trusting a remote node. Ask the node's operator for a trust bundle. The operator produces one with @node_trust and sends it to you, and you import it with /trust <bundle> [host], which records that node's certificate so every later connection must match it. Check the fingerprint with the operator by another route before you rely on it. If a later connection does not match the bundle, the client refuses the connection instead of making it, and it tells you the certificate did not match. /untrust [host] forgets a bundle, and connections to that node are UNVERIFIED again and will say so.

How do I… make a room and invite someone?

1Stand in a zone, then create the room. Rooms live inside zones (public, common, or private); creating one from your home hub or a Hall hub is refused, with a hint naming the zones you can enter.

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

2Share it so others can reach it (this also opens a presence/chat channel). Sharing a room does not move you into it. You stay where you are.

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.)

In the Urchin client you don't need the roster first: anyone you can see offers Whisper — click their name.

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               share the board, read-only

Shares are read-only. --post is refused: a share that grants posting grants it to everyone the board is shared with, which is not something the current build can scope to one person. Anyone you share a board with can read it; nobody gains the ability to post by being shared it.

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

Owner rights & grants

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. In the world view, the ACTIONS panel carries the social verbs — each entry dispatches the typed command it names; on Android the world is the primary way in.

Glossary