name: tlon
description: Interact with Tlon/Urbit beyond the channel plugin. Use for contacts (get/update profiles, nicknames, avatars), listing channels/groups, fetching message history, posting to channels, sending DMs, and ship lookups. Complements the Tlon channel - use this skill for read operations, profile management, and direct API access.

Tlon Skill

Provides direct Urbit API access beyond what the Tlon channel plugin offers.

Setup

Scripts require these environment variables (from gateway config):
- URBIT_URL - Ship URL (e.g., https://myship.tlon.network)
- URBIT_SHIP - Ship name (e.g., ~sampel-palnet)
- URBIT_CODE - Ship access code

The skill reads these from your Tlon channel config automatically.

Available Scripts

Posting to Channels

Send a message to a channel:

npx ts-node scripts/posts.ts send chat/~host/channel-name "Hello everyone!"

Reply to a post:

npx ts-node scripts/posts.ts reply chat/~host/channel-name <post-id> "Great point!"

React to a post:

npx ts-node scripts/posts.ts react chat/~host/channel-name <post-id> 👍

Remove a reaction:

npx ts-node scripts/posts.ts unreact chat/~host/channel-name <post-id>

Delete a post:

npx ts-node scripts/posts.ts delete chat/~host/channel-name <post-id>

Direct Messages

Send a DM:

npx ts-node scripts/dms.ts send ~sampel-palnet "Hey, how's it going?"

Reply in a DM thread:

npx ts-node scripts/dms.ts reply ~sampel-palnet <post-id> "Thanks for the reply!"

React to a DM:

npx ts-node scripts/dms.ts react ~sampel-palnet <post-id> ❤️

Remove reaction from a DM:

npx ts-node scripts/dms.ts unreact ~sampel-palnet <post-id>

Delete a DM:

npx ts-node scripts/dms.ts delete ~sampel-palnet <post-id>

Accept a DM invite:

npx ts-node scripts/dms.ts accept ~sampel-palnet

Decline a DM invite:

npx ts-node scripts/dms.ts decline ~sampel-palnet

Send to a group DM (club):

npx ts-node scripts/dms.ts send 0v4.club-id "Message to the group"

Contacts

Get all contacts:

npx ts-node scripts/contacts.ts list

Get a specific contact's profile:

npx ts-node scripts/contacts.ts get ~sampel-palnet

Add a contact:

npx ts-node scripts/contacts.ts add ~sampel-palnet

Remove a contact:

npx ts-node scripts/contacts.ts remove ~sampel-palnet

Sync (fetch) profiles from ships:

npx ts-node scripts/contacts.ts sync ~sampel-palnet ~zod

Update your profile:

npx ts-node scripts/contacts.ts update-profile --nickname "My Name" --bio "About me" --status "Available"

Update your avatar:

npx ts-node scripts/contacts.ts update-profile --avatar "https://example.com/avatar.png"

Channels

List DMs:

npx ts-node scripts/channels.ts dms

List group DMs:

npx ts-node scripts/channels.ts group-dms

List subscribed groups:

npx ts-node scripts/channels.ts groups

Groups

List your groups:

npx ts-node scripts/groups.ts list

Create a new group:

npx ts-node scripts/groups.ts create "Group Name" [--description "..."]

Get group info:

npx ts-node scripts/groups.ts info ~ship/group-slug

Invite members:

npx ts-node scripts/groups.ts invite ~ship/group-slug ~invitee1 ~invitee2

Leave a group:

npx ts-node scripts/groups.ts leave ~ship/group-slug

Join a group:

npx ts-node scripts/groups.ts join ~ship/group-slug

Add a channel to a group:

npx ts-node scripts/groups.ts add-channel ~ship/group-slug "Channel Name" [--kind chat|diary|heap] [--description "..."]

Group Administration (Host Only)

Delete a group:

npx ts-node scripts/groups.ts delete ~ship/group-slug

Update group metadata:

npx ts-node scripts/groups.ts update ~ship/group-slug --title "New Title" [--description "..."] [--image "https://..."]

Kick members:

npx ts-node scripts/groups.ts kick ~ship/group-slug ~member1 ~member2

Ban members:

npx ts-node scripts/groups.ts ban ~ship/group-slug ~member1 ~member2

Unban members:

npx ts-node scripts/groups.ts unban ~ship/group-slug ~member1 ~member2

Set group privacy:

npx ts-node scripts/groups.ts set-privacy ~ship/group-slug public|private|secret

Accept join requests (for private groups):

npx ts-node scripts/groups.ts accept-join ~ship/group-slug ~requester1 ~requester2

Reject join requests:

npx ts-node scripts/groups.ts reject-join ~ship/group-slug ~requester1 ~requester2

Role Management

Add a role:

npx ts-node scripts/groups.ts add-role ~ship/group-slug role-id --title "Role Name" [--description "..."]

Delete a role:

npx ts-node scripts/groups.ts delete-role ~ship/group-slug role-id

Assign role to members:

npx ts-node scripts/groups.ts assign-role ~ship/group-slug role-id ~member1 ~member2

Remove role from members:

npx ts-node scripts/groups.ts remove-role ~ship/group-slug role-id ~member1 ~member2

Activity / Notifications

Get recent mentions:

npx ts-node scripts/activity.ts mentions [--limit N]

Get recent replies:

npx ts-node scripts/activity.ts replies [--limit N]

Get all recent activity:

npx ts-node scripts/activity.ts all [--limit N]

Get unread counts:

npx ts-node scripts/activity.ts unreads

Messages

Get recent messages from a DM:

npx ts-node scripts/messages.ts dm ~sampel-palnet --limit 20

Get recent messages from a channel:

npx ts-node scripts/messages.ts channel chat/~host/channel-slug --limit 20

Fetch full message history (same as channel):

npx ts-node scripts/messages.ts history "chat/~host/channel-slug" --limit 50

Search messages in a channel:

npx ts-node scripts/messages.ts search "query" --channel chat/~host/channel-name

Channel format:
- DMs: chat/~ship/dm (auto-converted from dm ~ship)
- Group channels: chat/~host/channel-slug
- Examples: chat/~nocsyx-lassul/bongtable, chat/~host/general

Notebooks (Diary Channels)

Post to a notebook:

npx ts-node scripts/notebook-post.ts diary/~host/channel-name "Post Title"

Post with a cover image:

npx ts-node scripts/notebook-post.ts diary/~host/channel-name "Post Title" --image https://example.com/cover.png

Post with rich content from a JSON file:

npx ts-node scripts/notebook-post.ts diary/~host/channel-name "Post Title" --content article.json

Post with content from stdin:

echo '[{"inline":["Hello, world!"]}]' | npx ts-node scripts/notebook-post.ts diary/~host/channel-name "Post Title" --stdin

Content format is Tlon's Story structure - an array of verses:

[
  { "inline": ["Plain text or ", { "bold": ["bold"] }, " text"] },
  { "block": { "header": { "tag": "h2", "content": ["Section Title"] } } },
  { "block": { "code": { "code": "const x = 1;", "lang": "javascript" } } },
  { "inline": [{ "blockquote": ["A wise quote"] }] }
]

API Reference

See references/urbit-api.md for Urbit HTTP API details.

Notes

• All ship names should include the ~ prefix (scripts will normalize if missing)
• Profile updates sync to peers automatically via the contacts agent
• Post IDs are Unix timestamps in milliseconds
• For sending messages via the Moltbot message tool, use channel=tlon
• Channel nests follow format: <kind>/~<host>/<name> where kind is chat, diary, or heap