CLI Command Reference¶
Checked against the node's verb table on 2026-09-30. Every command on this page is registered in
UnifiedVerbManager._register_all_verbs(src/kunuleco/verbs/unified_verbs.py), and each syntax line is the verb's own usage string.
This page lists the commands the Kunuleco node accepts, by category. You type them in the Urchin
terminal or over an SSH or raw-text connection. The Urchin client also has its own / commands,
which run in the client and never reach the node. They are listed in the manual's
Urchin client commands section, and help client prints them.
Command Syntax¶
Commands follow these patterns:
verb [arguments] # Standard commands
@command [arguments] # Diagnostic and network commands, plus older alias names
Arguments in <brackets> are required. Arguments in [brackets] are optional.
U-0 Normalization (2026-02-23): All commands now use clean MUD verb names. Old
@-prefixed names still work as aliases for backward compatibility.
Every command needs a signed-in session. A few commands, or some of their forms, are limited to
the node's owner, the account that holds the node_admin capability. They are debug,
@captp_debug, @ipfscleanup all, and the disable, enable and force forms of transport.
Anyone else who runs them is refused.
Quick Reference¶
| Category | Commands |
|---|---|
| Movement & Observation | look, peer, place, go, home, north/south/east/west/up/down |
| Objects | create, get, drop, put, destroy, inventory, describe |
| Communication | say, chat, tell, outbox, post, read, reply |
| People | friend, unfriend, friends, contacts, petname, petnames, finger, block, unblock, blocked |
| Presence | join, leave, invite, door, meet, share, who, whoami |
| Rooms | create ~room, describe room, exits, list, share room |
| Halls & Standing | found, standing, zones, halls, set hall, knocks, accept, reject, vouch, manifest |
| Capabilities | grant, revoke, delegations, undelegate, renew, yes |
| Services | service |
| Media | media |
| Identity | export-identity, import-identity, passwd |
| System | help, quit, debug, ping, bug, transport |
| Debug/Network | @peers, @discover, @vpeers, @torstatus, @ipfsid, and the rest below |
Movement & Observation¶
look¶
Examine your surroundings or a specific target.
look # Describe the current room, exits and objects
look <target> # Inspect an object in the room or your inventory
look <capsule> # Show a capsule's contents and services
look capsules # List every capsule here with its contents
Aliases: l
peer¶
List the contents of a capsule in your location.
Aliases: inspect
place¶
Show the current place as structured data. It gives the place's kind (home, hall, zone or room),
its children with their standing thresholds, its exits with destination names, and the capsules
in it. It does not move you. look is the prose form of the same read.
go / Movement¶
Move to another location.
go <direction|exit> # Move through an exit
go north
go garden
north # Same as 'go north'
n # Shorthand for north
Directions: north, south, east, west, up, down, northeast, northwest,
southeast, southwest. The one-letter forms n, s, e and w are registered. There are no
two-letter diagonal shortcuts.
Aliases: exit (same functionality)
home¶
Return to your home location.
Object Manipulation¶
create¶
Create a new object from a prototype.
create ~<prototype> [name] [options]
create ~capsule notes
create ~capsule as notes # Older 'as' form, still accepted
create ~object # Auto-generated name
create ~room <name> [--from <exit>] [--to <return>] [--desc ...]
create ~place workshop # Alias for ~room
create ~board <id> <name...>
create ~presence <name>
Prototypes: ~object, ~capsule, ~room (alias ~place), ~board, ~presence.
~game was removed in 0.2.139 and is refused.
create ~presence <name> makes a presence on this node with no room behind it. Its door is open
until its owner changes it with door.
Aliases: @room_create (for ~room), @board_create (for ~board)
get / take¶
Pick up an object from your current location.
drop¶
Put down an object you are carrying. It goes into a drop capsule in the current place, which is created if none exists.
put¶
Put an object you are carrying into a container.
destroy¶
Permanently remove an object or a Place.
destroy <name> # An object, by name or id
destroy capsule <name|capsuleN> [--force]
destroy hall <name> # A Hall in your Common zone
destroy room <name> # A room in the current zone
A single token that names a capsule, such as destroy capsule1, is treated as
destroy capsule capsule1. Homes and zones cannot be destroyed.
Aliases: @destroy_capsule (for the capsule form)
inventory¶
Show what you are carrying.
describe¶
Set a description. The first word picks what is described.
describe room [room_name] <description>
describe hall <text> # The Hall you are in
describe home <text> # Your home's look text
describe object <name> <short|long> <text>
describe capsule <name|capsuleN> <text>
describe hall needs Steward standing in the Hall. describe object needs you to be the object's
creator or a Steward of the Place that holds it. describe capsule needs Steward authority over
the capsule's Place.
Aliases: @room_describe, @describe_hall, @describe_home, @describe_object,
@describe_capsule
Communication¶
say¶
Speak to everyone in your current room. If the room has a shared presence, remote members hear it too.
chat¶
Send a message to your active channel, or to a named one. A channel is named only by a !
prefix, so chat never guesses whether the first word is a name.
chat <message> # Active channel, whole line
chat !<channel> <message> # A named channel
chat hello everyone # Sends "hello everyone" to the active channel
chat !garden looks nice # Sends "looks nice" to the garden channel
Addressing a channel never creates it and never moves you into it. create ~presence <name> and
join are the commands that do those things.
Everyday chat never names a host. Join a presence once, then type, or name a channel you are in
with !. chat does not read a <host>: prefix. chat alice#482938:lobby hi sends that whole line
as a message to your active channel, and chat !alice#482938:lobby hi is refused as an unknown
channel.
Naming a host¶
Two commands can name the node that hosts a presence:
join <host> <presence> # join alice#482938 lobby
@psay --to <host>:<presence> <message> # @psay --to alice#482938:lobby hello
@psay --to local:<presence> <message> # your own presence of that name
The host is a handle with its tag. In @psay --to, the part before the colon is read as a host only
when it carries # or is one of the local words local, self, here or me (or nothing, as in
:lobby). So hall:<name> and room:<name> stay presence names. The local words mean your own
presence of that name. A host this node does not know is refused, and the reply points you at
@peers.
Chat between two accounts on the same node, where one speaks in the other's presence, is covered once package S1d lands.
tell / whisper¶
Send a private message to one person, or show your recent history with them.
tell <friend> [message]
tell alice#482938 Hi there!
tell alice#482938 # Show your last 20 messages with alice
whisper bob#123456 Hello # Same as tell
The message is kept in a per-person history that survives a restart. If the person is offline, it waits in your outbox. A message to or from someone you have blocked is refused.
Aliases: whisper, @chat
@pwhisper is a separate, older command and not an alias of tell. It is listed under
Debug/Network below.
outbox¶
Show messages waiting for friends who were offline, or retry them now.
Aliases: @outbox
post¶
Post a message to a bulletin board. Name the board with --board. Without it the post goes to a board called
general, which the node no longer creates, so it is refused unless you made a general board of your own.
read / posts¶
Read bulletin board posts. Name the board with --board. Without it the command reads a board called general,
which the node no longer creates, so it is refused unless you made a general board of your own.
reply¶
Reply to a bulletin board post.
Board management¶
create ~board <id> <name...> # Create a board
list boards # List boards with post counts
share board <board_id> [--post] [revoke]
@board_delete_post <post_id> # Delete a post (its author or the board owner)
share board --post is refused. To let a person post, grant it with
grant board-<id> <identity> <caps> --service board.
Aliases: @board_create, @board_list, @board_share
People & Contacts¶
friend / unfriend¶
Add a peer to your contacts, or drop them. You can only friend someone this node has already seen.
friend is a local record. It sends nothing to the other person.
friends / contacts¶
Show your contacts.
friends # Roster with cached status
friends online # Poll every contact now
contacts # Plain-text contact list
Aliases: @friends (for friends)
@friend¶
Friend a peer and give them a petname in one step.
@friend add <identity> [petname]
@friend remove <identity-or-petname>
@friend rename <old-petname> <new-petname>
@friend list
petname / petnames¶
Give a peer a private name that only you see, or list the ones you have set.
finger¶
Show what this node knows about a peer, including their petname, canonical name and whether they have a live session. It is a local read and sends nothing over the network.
block / unblock / blocked¶
Refuse a person, lift the refusal, or list who you have blocked.
A block keys on the identifier (AID) the person proved, so it covers every record this node holds
for them and still holds after a reconnect, a Tor connection or a key rotation. It closes the open
connection to them. When the node cannot tell who the name belongs to, it says so and blocks
nothing. The replies begin Can't block '<name>' yet: this node has never verified who that ...
or Can't block '<name>': that name belongs to more than one identity ....
A block does not silence you in a Hall you share, it does not remove anyone from a Hall, and it does not tell the other person.
unblock restores the whole person to the relationship they had before the block. A former
contact comes back with They are back in your contacts. Messages held while they were blocked
go out once the connection is back.
Presence & Invites¶
join¶
Join a presence. A join is remote by default. Use --local to join a presence on this node.
join [--local] [--here] <identity|code|name> [presence]
join alice#482938 lobby # A remote peer's presence
join tiger-castle-7 # An invite short code
join --local mediachat # A presence on this node
join --here alice#482938 room:garden # Attach a remote room to your current location
join <peer-seed> # A kunul1... seed from 'meet'
Without --here, a remote room attaches to your Nexus. The presence's door decides whether you
are admitted. A refused join reports the host's reason.
Aliases: @pjoin, @vjoin
leave¶
Leave a presence, or drop a remote Hall reference.
leave [presence_name] # Leave the current or a named presence
leave hall <name> # Remove a remote Hall reference
If you leave your only presence, you rejoin the lobby.
Aliases: @pleave (for the presence form)
invite¶
Create an invite to a presence. With no name, it invites to your current presence.
invite [presence] [-short] [-noshort]
invite lobby
invite # Your current presence
share presence [name] # Same command
It prints an invite string of the form join <your-name> <presence>, a short code when the
bootstrap service gives one, and a QR code of the invite string. The invite carries no permission
of its own. Whether a join is admitted is decided by the presence's door.
Aliases: @pinvite
door¶
Control who may join a presence you created with create ~presence.
door <presence> [open|invite] | door <presence> invite|uninvite <person>
door officers # Show its door and how many are invited
door officers invite # Only invited people may join
door officers open # Anyone who knows its name may join (the default)
door officers invite ana#123456 # Invite a person
door officers uninvite ana#123456
Only the presence's owner can change its door, and the lobby is always open. An invite names a proven identity. That is the name a connection proved, the exact name of an account signed in on this node, or a reference.
A room's door is its threshold, set with
set hall threshold from inside the room. How a room's door and its knocks work is covered once
AUTH-94's fix lands.
meet¶
Show a peer seed for an in-person connection on the same local network.
meet # Print your kunul1... seed and a QR code
meet guest # Print this node's host:port and a QR for the Urchin app's server field
The other person runs join <seed>. The seed is valid while this node stays on that network.
share¶
Share a room, capsule, board, Hall or presence.
share <room|capsule|board|hall|presence> <name> [revoke] [--post] [--no-presence]
share presence # Invite to your current presence
share room <room_name> [<person>] [revoke] [--monitor]
share capsule <capsule_name> [revoke] [--no-presence]
share board <board_id> [--post] [revoke]
share hall <name> [revoke]
A room share never moves you into the room. A capsule share creates the capsule's presence and
joins you to it, replying Auto-created presence '<name>' (you are now in it), unless you pass
--no-presence. Only a capsule's owner can share it.
What share room <room> <person> admits, and how it
interacts with the room's knocks, is covered once AUTH-94's fix lands.
Aliases: @room_share, @capsule_share, @board_share, @hall_share
who¶
Show who is in the current room and everyone signed in on this node.
@presences / @pwhere / @pstats¶
@presences # List active presences
@pwhere # Show which presence you are in
@pcurrent # Same as @pwhere
@pstats # Presence system statistics
Rooms¶
Rooms are created with create ~room, described with describe room, and shared with
share room. The remaining room commands are below.
exits¶
Manage a room's exits.
exits <room> add <exit_name> <target_room> [--oneway]
exits <room> remove <exit_name>
exits garden add north lounge
exits garden add secret_door vault --oneway
Aliases: @room_exits (takes exits add|remove ... without the room name)
list¶
List rooms, capsules, boards or grants.
list <rooms|capsules|boards|grants> [options]
list rooms
list capsules
list boards
list grants [capsule]
Aliases: @room_list, @capsule_status, @board_list, @capsule_grants
Halls & Standing¶
found¶
Found a Hall in your home's Common zone. It gets Public, Common and Private zones and three starter rooms, and you become its Steward.
standing¶
Show your Standing in the current Hall, or, as a Steward, grant one.
Tiers are newcomer, familiar, trusted and steward. visitor clears a grant.
In this build a grant does not take effect. A name answers Cannot resolve user '<name>' to a DID., and a
did:key target writes a row the Hall's gates never read, because they look people up by AID. See
Known issues.
Aliases: @standing
zones / halls¶
zones # The zones in the current Place and your access to each
halls # Halls you hold any Standing in
Aliases: @zones, privacy, @privacy (for zones), @halls (for halls)
set hall¶
Change a Hall's settings. You must be a Steward and stand inside the Hall.
set hall atmosphere <Supportive|Focused|Playful|Intellectual>
set hall threshold <open|knock|invite_only|members_only>
set hall harbor <public|private>
set hall vouch_restores <on|off>
set hall voice <on|off>
set hall pose <on|off>
set hall residency <on|off>
set hall verb add <alias>
set hall verb remove <alias>
voice gates live voice in the Hall and pose gates live avatar movement. When the field is
unset, voice is off and pose is on. found hall sets both on for a new Hall. Voice notes are not affected by
set hall voice.
knocks / accept / reject / vouch¶
Handle people waiting at a Hall's threshold.
knocks # Pending knocks on Halls you Steward
accept <user> # Steward admits a knock as Newcomer
reject <user> # Steward refuses a knock
vouch <user> # A Trusted member vouches for a knock
accept, reject and vouch act in the Hall you are standing in.
Running knocks and accept inside a room is covered once
AUTH-94's fix lands.
Aliases: @knocks, @vouch
manifest¶
Open a portal in your Nexus to the Realm of another account on this node.
Capabilities & Services¶
grant¶
Grant capabilities on a capsule you own.
grant <capsule> <identity> <caps> [--service <svc>]
grant meepcap tim#482938 read,write
grant meepcap tim#482938 read --service inventory
Capsule delegation (package 7e) is covered once it lands.
Aliases: @capsule_grant
revoke¶
Revoke capabilities on a capsule you own. With no capabilities named, it revokes every capsule-level grant to that identity.
revoke <capsule> <identity> [caps] [--service <svc>]
revoke meepcap tim#482938 write
revoke meepcap bob#482938
revoke meepcap tim#482938 read --service inventory
Aliases: @capsule_revoke_grant
delegations / undelegate¶
List and revoke grants that are not on a capsule, such as create_user, node_admin and their
delegate: rights.
delegations # Live grants you gave or hold, with their ids and expiry
undelegate <delegation-id> # Revoke a grant and what was passed on from it
The owner sees every such grant on the node. undelegate refuses the trust root's own grants and
the last node_admin. Use revoke for capsule grants.
Self-grants (package 7d) are covered once it lands.
renew / yes¶
Renew grants you gave that expire. create_user, node_admin and every delegate:* grant expire
90 days after they are granted unless the granter renews them. The trust root's grants do not
expire, and nothing renews by itself.
renew <name> # Renew every expiring grant you gave that person
renew all # List what would be renewed, and sign nothing
yes # Renew exactly the list 'renew all' just showed
renew all ends with Nothing has been signed. Type yes to renew exactly these. yes works
once, on the same connection, within 10 minutes of the list.
service¶
Manage the services on a capsule, or call a service a peer has shared with you.
service <add|list|remove> <capsule> [template]
service invoke <peer_name> <method_name> <capsule_name> [args...]
service list meepcap
service add meepcap echo
service remove meepcap echo
Aliases: @capsule_service, @capsule_invoke
Media¶
media¶
Upload, list and share media, and set how long received media is kept.
media upload <filepath> [--caption "text"]
media list
media info <id>
media share <id> [presence]
media delete <id>
media retention [days|sweep]
media upload reads a file on the node's own filesystem. media delete removes the record.
media retention <days> sets how long this node keeps media other people shared with it, from 1
to 365 days, and media retention sweep runs the expiry now. Your own uploads stay until you
delete them.
Identity & Account¶
whoami¶
Show your name, location and inventory.
@whoami¶
Show your P2P identity.
export-identity¶
Write your identity to an encrypted file. The passphrase must be base64-encoded. The client normally runs this for you, so the passphrase does not end up in history.
import-identity¶
Restore an identity from an encrypted file. The file must be in the node's imports folder
(<data>/imports), named relative to that folder. It refuses to replace an existing identity
unless you pass --overwrite, and it refuses a name another account holds.
After an import, restart the session and sign in as that identity.
passwd¶
Change your password. The node handles PASSWD before normal command dispatch. The passwd verb
exists so help passwd can explain it.
System Commands¶
help¶
Get help on commands.
help # Getting started
help all # Full listing
help debug # Diagnostic commands
help client # Urchin client commands
help <verb> # Help for one command
? # Shorthand for help
quit¶
Disconnect from the node.
debug¶
Show diagnostic information. Owner only.
ping¶
Check whether a peer is connected, and over which transports.
bug¶
Save a JSON snapshot of node state for a bug report. It is written to a local file and never uploaded.
Aliases: @bug
transport¶
Show your transports, or turn one off for testing. The disable, enable and force forms are
owner only and affect every session on the node.
transport [status]
transport disable <mdns|ipfs|veilid|tor>
transport enable <mdns|ipfs|veilid|tor|all>
transport force <mdns|ipfs|veilid|tor|none> # Pin the next join (none clears the pin)
Aliases: transports, @transport, @transports
Node status¶
@version # Build version and commit hash
@node_processes # State of the IPFS, Tor, Veilid and CapTP daemons
@node_trust # This node's trust bundle, for giving a client out of band
@health # CapTP session health and reconnect state
@captp_debug # CapTP sessions and export tables (owner only)
Debug/Network¶
@discover¶
List the peers this node has sighted on the local network. A sighting is only a hint. It starts
a dial to the signed CapTP hello, and the hello decides who is there. A peer is marked ✓ only
when a verified session exists, under the name its hello proved.
@peers¶
List connected peers across all transports.
@netcheck¶
Check the network for P2P compatibility.
@whoknows¶
Show the peers this node knows how to reach.
@pconnect¶
Connect to a peer by their handle, trying the available transports together.
@piroshow¶
Show this node's PIRO document with all of its endpoints.
@psay / @pwhisper¶
Older presence and private-message commands. chat and tell are the current forms.
@psay [--to <presence>] <message>
@psay --to <host>:<presence> <message>
@pwhisper <peer_name> <message>
@psay --to is the one send that names a host. See Naming a host under chat.
Veilid Commands¶
@veilidstatus # Veilid bridge status
@veilidroute # Your route blob, for sharing by hand
@veilidconnect <peer_name> <route_blob> # Connect with a peer's route blob
@veilidsend <peer> <message> # Send a test message
@vpeers # Peers connected over Veilid
@vcaptp [peer_name] # CapTP session status with a Veilid peer
@vleave # Leave a remote presence and return to local
join connects over Veilid when it needs to, so @veilidconnect is rarely needed.
Tor Commands¶
@torstatus # Tor bridge status
@toraddress # Your .onion address
@torconnect <peer_name> <onion_address> # Connect to a peer over Tor
IPFS Commands¶
@ipfsid # Your IPFS peer ID and addresses
@ipfspeers # IPFS swarm peers
@ipfscleanup # Close Kunuleco's p2p streams
@ipfscleanup status # Show active streams
@ipfscleanup all # Close every p2p stream (owner only)
@p2pstatus # IPFS P2P bridge status
@p2pconnect <peer-id> # Connect to a peer over IPFS P2P
@p2pdisconnect <peer-id> # Disconnect from an IPFS peer
Environment Variables¶
Commands may be affected by these environment variables:
| Variable | Default | Purpose |
|---|---|---|
IPFS_API_URL |
http://127.0.0.1:5001 |
IPFS API endpoint |
See Also¶
- Getting Started — First steps tutorial
- Transports Guide — Transport configuration
- Troubleshooting — Common issues
- Urchin client commands in the manual