5title: Messaging (:talk)
14`:talk` is the built-in frontend for the Urbit messaging and notifications
15protocol, `:hall`. Today we use `:hall` just to chat and coordinate, but
16it's really a general purpose piece of infrastructure.
18For the time being come join us in `/urbit-meta` by using the
19<a href="#-quickstart">quickstart</a> below.
21Today `:hall` is sort of like a distributed, encrypted Slack that can be
22used from the CLI and the browser. There’s no central `:hall` server.
23Any Urbit can host one.
25`:hall` is a general purpose tool for both aggregating and publishing
26streams of messages. Applications can use `:hall` as their transport
27protocol, API connectors can push disparate data sources into `:hall`,
28and so on. There are lots of things a distributed message protocol can
29be used for that we haven't even thought of.
31Here we'll be discussing how to operate the default CLI frontend, `:talk`,
32to send and receive messages. For a more in-depth look at `:hall`'s
33internals, take a look at its [documentation](#TODO).
41For the most part we use `:talk` as a single-instance of Slack: one main
42channel (`/urbit-meta`) and direct messages. Everyone is more than welcome
43in `/urbit-meta`. It's the place to get help, ask questions and chat about
46Let's join `/urbit-meta`:
48Use `ctrl-x` to switch from `:dojo` to `:talk`.
52 ~your-urbit:talk[] ;join /urbit-meta
56 --------------| ;join /urbit-meta
57 --------------| new glyph '>'
60Post a line to `/urbit-meta`:
62 ~your-urbit:talk> hello, world
64You'll see, echoed back at you:
66 ~your-urbit> hello, world
68To send a direct message to someone, first set your audience:
70 ~your-urbit:talk> ;~talsur-todres
72You'll see your prompt change:
74 ~your-urbit:talk[~talsur-todres]
76Now you and `~talsur-todres` can exchange messages directly.
78To set your audience back to `/urbit-meta`:
80 ~your-urbit:talk> ;/urbit-meta
82Use `;leave` to unsubscribe from a channel:
84 ~your-urbit:talk> ;leave /urbit-meta
86There are two ways of using `:talk`: from the CLI or through a web ui
87available at `http://your-urbit.urbit.org/talk` (or
88`http://localhost:8080/talk`).
90The web ui ships as compiled JavaScript on your Urbit, but has its own
91source repo [here](https://github.com/urbit/talk).
93Last, let's create a channel we can invite some friends to:
95 ~your-urbit:talk> ;create channel %my-channel 'some description'
97Now you can tell your friends to `;join ~your-urbit/my-channel`.
101`:hall`'s design is similar in spirit to
102[nntp](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
103the underlying protocol for Usenet.
105Our design is pretty simple: `:hall` messages go to ‘circles’. Any urbit
106can host or subscribe to any number of circles.
108There are four kinds of circles: a write-only `%mailbox` for direct
109messages, an invite-only `%village` for private conversation, a read-only
110`%journal` for curated content, and a public-access `%channel` for
115A post can be a variety of different data structures. Let's look at the
116ones you can use from within `:talk`: lines, URLs, expressions and
121A line is simply a string of text. Depending on the filtering rules set
122by the circle's host, these may or may not include uppercase and Unicode
124If the line starts with `@`, it's an action (IRC `/me`).
126 ~your-urbit:talk> @sends a message
130 ~your-urbit sends a message
134A URL is any valid URL.
136 ~your-urbit:talk> http://example.com/
140Expressions can be used to show and evaluate Hoon code. Send an expression
141by prefacing your message with `#`.
143 ~your-urbit:talk> #(add 1 2)
147 ~your-urbit# (add 1 2)
152To indicate what you're saying is in direct response to a specific
153message, select the message (see Activating Lines below) and type your
156 ~some-urbit> hello! how are you?
157 ~your-urbit:talk> ; good, thanks!
161 ~your-urbit>^ good, thanks!
165A line number identifying the *subsequent* line is displayed every 5
169 ~your-urbit> this is my message
170 ~your-urbit> this is another message
171 ~your-urbit sends a message
172 ~your-urbit/ http://example.com/
173 ~your-urbit# (add 1 2)
176 ~your-urbit>^ that's my message!
178You can use a line number to *activate* a line:
182which prints the number, line identifier, timestamp, sender, audience,
186 0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
187 ~your-urbit to ~another-urbit
188 in reply to: ~your-urbit:
192If information got truncated — like happens for long URLs or expressions —
193or if there's additional information available — as is the case with
194replies and attachments — activating the message will show you all the
197You can activate the most recent line with `;`, the second-most recent
200### Creating and managing circles
202`;create [type] %name 'description'`
203Creates and joins a circle, where `[type]` is any of the following:
204- `channel`: public circle. Has a blacklist for write control.
205- `village`: invite-only circle.
206- `journal`: publicly readable, invite-only for writing.
207- `mailbox`: publicly writeable, can only be read by its host.
209`;delete %name 'optional reason'`
210Deletes a circle. If a reason is specified, that gets sent to all
211subscribers before the circle gets deleted.
213`;depict %name 'description'`
214Changes the description of circle `%name`.
216`;filter %name [capitals] [unicode]`
217Configures the message filter for circle `%name`: whether to allow
218capital and/or unicode characters. `y`/`&`/`true` for allowed,
219`n`/`|`/`false` for disallowed.
221`;invite %name ~someone`
222Invite someone into your circle `%name`. If they were previously banished,
223removes them from the blacklist.
224Can also invite multiple ships at once, `~comma, ~separated`.
226`;banish %name ~someone`
227Banish someone from your circle `%name`. If they were previously invited,
228removes them from the whitelist.
229Can also banish multiple ships at once, `~comma, ~separated`.
231`;source %name ~other/circle`
232Adds `~other/circle` as a source for circle `%name`. This causes all
233messages sent to `~other/circle` to also appear in `%name`.
235`;unsource %name ~other/circle`
236Removes `~other/circle` as a source for circle `%name`.
240If you have joined a circle, you can make this information publicly
241publicly available to help others find that circle as well.
244Adds a circle to your public membership list.
247Removes a circle from your public membership list.
251You'll see status notifications when people enter or leave stations
255Turn off status (and config) notifications.
258Turn on status (and config) notifications.
261List everyone in all your subscribed circles. Optionally specify a
262specific circle to list members of just those.
264`;attend ~some/circle [presence]`
265Manually set your presence to show up as one of the following. (In the
266future, a sufficiently advanced client can automatically set these for
271- `gone` - not present
273`;name ~some/circle 'my handle'`
274Set a handle ("name") for yourself in a specific circle. It will display
275to users who have done `;set nick`, but gets truncated if it's longer
280An audience consists of one or more messaging targets. These can be
281circles or ships. (In the latter case, it's secretly the `~ship/inbox`
286Glyphs are assigned by circle hash out of the following list
288 > = + - } ) , . " ' ^ $ % & @
290Alphanumeric characters and `|#;:*~_` are reserved; all others (the
291above list, and `\/!?({<`) can be manually assigned.
294Assigns the `+` glyph to `/urbit-test`.
296`;unbind + /urbit-test`
297Unassigns the `+` glyph from `/urbit-test`.
299To see what circle is bound to a glyph:
306Received posts are prefixed with a glyph to let you know what the
307audience is. You can activate an individual post to see the full
309There are a few special-purpose glyphs.
311- `|` - Informational messages
312- `:` - Posts directly to you
313- `;` - Posts to you and others (a multiparty conversation)
314- `*` - Posts to a complex audience that doesn't directly include you.
318The audience you're sending to is always shown in your prompt. If
319there's a glyph for it, it's shown as the glyph.
321Here we're talking to the station bound to `=`:
325Here we're talking directly to `~dannum-mitryl`:
327 ~your-urbit:talk[~dannum-mitryl]
332Set audience to `~urbit/station`.
335Set audience to the station bound to the `=` glyph.
338Set audience to `~dannum-mitryl` (a direct post).
341Set audience to a station on your own ship.
343`;~dannum-mitryl this is a private message`
344Set the audience and send a post to it. This works for all of the above.
346Your audience is configured 'implicitly' with regard to the following
349- if you manually locked the audience, that audience.
350- if typing a post, the audience when you started typing.
351- if you activated a post, the post you activated.
352- audience of the last post received.
353- audience of the last post sent.
355Clear any 'implicit' audience setting by moving your cursor to the start
356of the line and pressing backspace (whether the line is empty or not).
357Posting a line clears the typing and activation configurations.
362List all local nicknames.
370`;nick ~your-urbit plato`
374Clear an assigned nickname.
377Show nicknames instead of urbit names. If no local nickname is set, uses
378that user's handle. If the user has no handle, just the urbit name.
381Show urbit names instead of nicknames.
383Nicknames and handles longer than 14 character will be truncated in
384output. Nicknames are strictly local - like the names on entries in a
387### Miscellaneous configuration
390Show the timestamp for each message.
393Stop showing the timestamp for each message.
395`;set timezone [+/-][hours]`
396Adjust the display of the timestamps to a specific timezone. Relative to UTC.
399Emit a terminal bell sound if your six-syllable ship name is mentioned in
403Do not notify when your ship name is mentioned.
406Set the rendering width of `:talk` to a specific number of characters.
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list