@@ -0,0 +1,1873 @@
3+template = "page_indiced.html"
7+## Admin and Operations {#urbit-administration}
9+Your urbit (also called your _ship_) is a persistent Unix process that you
10+mainly control from the console. For some things, a browser will also work.
14+You can turn your urbit off with `Ctrl-d` from the Talk or Dojo prompts.
16+You can force-quit your urbit with `Ctrl-z` from anywhere.
20+To restart your urbit simply pass the name of your pier:
34+To log an urbit's command line output to a file, use `script`:
37+$ script urbit.log urbit your-urbit
42+Piers are designed to be portable, but it _must_ be done while the urbit
43+is turned off. Urbit networking is stateful, so you can't run two copies
44+of the same urbit in two places.
46+To move a pier, simply move the contents of the directory it lives in.
47+To keep these files as small as possible we usually use the `--sparse`
48+option in `tar`. With a pier `your-urbit/`, something like this should work:
51+tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
52+scp your-old-server:~/your-urbit.tar.gz your-new-server:~
55+Then to unzip it, on your other Unix server, run:
58+tar xfvz your-urbit.tar.gz
61+Delete the tar file, and, after installing Urbit on your new server,
62+start your urbit back up with:
70+Your Urbit terminal is separated into two parts: the prompt (the bottom
71+line) and the record (everything above that). The record is shared; all
72+the output from all the apps in your command set appears in it. The
73+prompt is multiplexed.
75+In the CLI, Urbit apps can process your input before you hit return. To
76+see this in action try entering `)` as the first character at the Dojo
77+prompt. Since there is no Dojo command or Hoon expression that starts
78+with ')', the Dojo rejects it.
80+`Ctrl-x` - Switches the prompt between running console apps
82+`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack
85+`Ctrl-d` - From Talk or Dojo, stops your Urbit process.
87+`Ctrl-z` - Stops the Urbit process from _anywhere_.
89+`↑` / `↓` - History navigation
91+The following emacs-style key bindings are available:
94+Ctrl-a Cursor to beginning of the line (Home)
95+Ctrl-b Cursor one character backward (left-arrow)
96+Ctrl-e Cursor to the end of the line (End)
97+Ctrl-f Cursor one character forward (right-arrow)
98+Ctrl-g Beep; cancel reverse-search
99+Ctrl-k Kill to end of line
100+Ctrl-l Clear the screen
101+Ctrl-n Next line in history (down-arrow)
102+Ctrl-p Previous line in history (up-arrow)
103+Ctrl-r Reverse-search
104+Ctrl-t Transpose characters
105+Ctrl-u Kill to beginning of line
106+Ctrl-y Yank from kill buffer
111+On startup Urbit tries to bind to `localhost:80`. If you're already
112+running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit
113+that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web
114+domains through Urbit's own servers. Any planet `~your-urbit` is also at
115+`your-urbit.arvo.network`, but only after you [set up DNS](../dns-proxying).
117+Your urbit serves a simple homepage from `http://localhost` or
118+`https://your-urbit.arvo.network` that should be self-explanatory. Since
119+our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.
120+You can find that on `8443`. Or `8444` (and so on) if you're already
121+running something on `8443`.
125+Planets can spawn moons, which are meant for connected devices: phones, smart
126+TVs, digital thermostats. The basic idea is: your planet runs permanently in a
127+data center somewhere and moons run on all your devices. Each planet can issue
128+~4 billion (`2^32`) moons.
130+To generate a random moon from your planet, run:
133+~sampel-palnet:dojo> +moon
134+moon: ~faswep-navred-sampel-palnet
135+\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
136+ .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
137+ x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
141+You must manually edit the output of `+moon` to get
142+the correct format for the `<key>`:
146+- combine into one line, omitting spaces
148+- trim the leading `~.`
150+`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
153+Put `<key>` in a file and that file becomes `<keyfile>`.
155+Another way of generating `<keyfile>` is:
158+~sampel-palnet:dojo> @moon/key +moon
159+moon: ~faswep-navred-sampel-palnet
162+`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
163+and does not need editing to be used with the `-k` option.
165+You can use the resulting output in the same installation flow from the
166+[Booting a Ship](@/docs/getting-started/booting-a-ship.md) guide, following the same scheme as for booting a planet. That scheme is:
169+$ urbit -w <moonname> -G <key> -c <piername>
175+$ urbit -w <moonname> -k <keyfile> -c <piername>
178+The `-c <piername>` argument is not required, but it is recommended; otherwise,
179+the resulting directory is a rather unwieldy moon name.
181+Here's how an example moon might be booted:
184+$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
190+$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
193+Moons are automatically synced to their parent `%kids` desk, and can control
194+applications on their parent planet using `|link`.
196+### Continuity breaches
198+While the Urbit network is in this alpha state, we sometimes have to
199+reboot the whole network. This happens either when major changes need
200+to be shipped or we hit a bug that can't be fixed over the air.
202+Because Urbit networking is stateful we call this a _continuity breach_.
203+Everything has to be restarted from scratch. Your pier will continue to
204+function after we have breached, but it wont connect to the rest of the
207+When this happens, back up any files you'd like to save, shut down your
208+urbit and recreate it (as if you were starting for the first time).
211+## Creating a Comet {#creating-a-comet}
214+**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
216+`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`
218+Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network.
222+To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
228+This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
231+ames: on localhost, UDP 31337.
232+http: live (insecure, public) on 8080
233+http: live ("secure", public) on 8443
234+http: live (insecure, loopback) on 12321
239+## DNS Proxying {#dns-proxying}
241+We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.
243+Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
245+### Planets and Stars
247+For a planet or star's DNS proxying request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.
249+To get `ship.arvo.network` on a planet or star, you must set up DNS routing with its parent ship by starting the `:dns` app.
250+To do so, simply run this command in your ship's Dojo:
256+You'll then be prompted to enter the public IP address of your ship. You can also pass the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:
259+> :dns|request .1.2.3.4
262+`:dns`, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `%bail-early` message in `:talk`; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, your local `:dns` app will send a `:talk` message saying `awaiting response from ~zod`.
264+The request will be picked up shortly, and the `ship.arvo.network` DNS record will be set to the given IP address. Once that's setup, `~zod` will be notified, and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain, and say `confirmed access via ship.arvo.network`.
266+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend using Chrome or Brave.
270+Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.
272+There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
278+This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.
280+Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, talk messages, and so on.
284+Configuring a ship's domain causes the `:acme` app to request an HTTPS certificate for that domain from LetsEncrypt. Note that LetsEncrypt also requires that the HTTP server be listening on port 80. If the certificate request fails, `:acme` will send a `:talk` message with an explanation. Once the certificate is successfully retrieved, `:acme` will install it, causing the HTTP servers to restart. A secure server will be started on port 443 (the HTTPS default) if it's available. Otherwise, it will try 8443, and then increment to the next port until it can successfully bind one.
286+The built-in logic for listening on port 80 similar. Urbit tries to bind port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent version of macOS. Otherwise, the process needs to either be run as root, or be given special permission (CAP\_NET_BIND on Linux).
289+## Messaging {#messaging}
291+Talk is the built-in frontend for the Urbit messaging and notifications
292+protocol, Hall. Today we use Hall to chat and coordinate, but it's really
293+a general purpose piece of infrastructure.
295+For the time being come join us in `~dopzod/urbit-help` by using the
296+'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
297+channel on that ship.
299+Today, Hall is sort of like a distributed, encrypted Slack that can be
300+used from the CLI and the browser. There’s no central Hall server.
301+Any urbit can host one.
303+Hall is a general purpose tool for both aggregating and publishing
304+streams of messages. Applications can use Hall as their transport
305+protocol, API connectors can push disparate data sources into Hall,
306+and so on. There are lots of things a distributed message protocol can
307+be used for that we haven't even thought of.
309+Here we'll be discussing how to operate the default CLI frontend, Talk,
310+to send and receive messages. For a more in-depth look at Hall's internals,
311+take a look at its [documentation](@/docs/learn/arvo/hall.md).
315+The most common uses of Talk right now are communicating over a public chat channel called `~dopzod/urbit-help` and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.
317+There are two ways of using Talk: from the terminal running the Urbit process, or through the Landscape web UI available at `http://localhost/~~/landscape`.
319+If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.
321+### Joining a channel
323+In Hall, a medium for a message is called a _circle_. There are four types of circles, but we for now we'll be dealing with the _channel_: a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#manual) section.
325+Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
330+~your-urbit:talk> ;join ~dopzod/urbit-help
333+Scrolling down your terminal window, you'll probably see the playback of
334+previous `~dopzod/urbit-help` messages that you missed.
336+Post a line to `~dopzod/urbit-help:`
339+~your-urbit:talk= Hello, world!
342+You'll see your message printed below messages from others that came before it:
345+~your-urbit= Hello, world!
348+### Subscribing to a channel in Landscape
350+In Landscape, you can always navigate to a channel by opening the menu, or using the shortcut `cmd-k`, then typing `go ~host-urbit/channel-name`. However, if you want to see messages in your inbox, you'll need to join from the Talk terminal.
355+;join ~dopzod/urbit-help
358+Now, navigate to `localhost/~~/landscape`. You should see recent messages under the "Recent" tab, and if you navigate to the "All" tab, you should see your subscription to `~dopzod/urbit-help` under "Chats".
362+To send a direct message to someone, first set your audience:
365+~your-urbit:talk= ;~talsur-todres
368+You'll see your prompt change:
371+~your-urbit:talk[~talsur-todres]
374+Now you and `~talsur-todres` can exchange messages directly.
377+~your-urbit:talk[~talsur-todres] Hey buddy!
380+To set your audience back to `~dopzod/urbit-help`:
383+~your-urbit:talk[~talsur-todres] ;~dopzod/urbit-help
386+You'll see your prompt change back:
392+You can also use the ASCII "glyph" assigned to your `~dopzod/urbit-help` circle as a shortcut:
395+~your-urbit:talk[~talsur-todres] ;=
399+(Your ship may have a different glyph than `=` for your circle)
401+Use `;leave` to unsubscribe from a channel:
404+~your-urbit:talk= ;leave ~dopzod/urbit-help
407+The web UI ships as compiled JavaScript on your urbit, but has its own
408+source repo [here](https://github.com/urbit/talk).
410+Last, let's create a channel we can invite some friends to:
413+~your-urbit:talk= ;create channel %my-channel 'Some description.'
416+Now you can tell your friends to `;join ~your-urbit/my-channel`.
422+Hall's design is similar in spirit to
423+[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
424+the underlying protocol for Usenet.
426+Our design is pretty simple: Hall messages are called _posts_. Posts
427+go to _circles_. Any urbit can host or subscribe to any number of circles.
429+There are four kinds of circles: a write-only `%mailbox` for direct
430+messages, an invite-only `%village` for private conversation, a read-only
431+`%journal` for curated content, and a public-access `%channel` for
436+A post can be a variety of different data structures. Let's look at the
437+ones you can use from within Talk: lines, URLs, Hoon and replies.
441+A line is simply a string of text. Depending on the filtering rules set
442+by the circle's host, these may or may not include uppercase and Unicode
443+characters (see [filter](#filter)).
445+If the line starts with `@`, it's an action (like `/me` in IRC).
448+~your-urbit:talk= @sends a message.
454+~your-urbit sends a message.
459+A URL is any valid URL.
462+~your-urbit:talk= https://example.com/
467+You can use Talk to evaluate Hoon code and share the result with everyone in a
468+Hall circle. To do so, preface your Hoon with `#`.
471+~your-urbit:talk= #(add 2 2)
477+~your-urbit# (add 2 2)
483+To indicate what you're saying is in direct response to a specific message, select the message (see Activating Lines below) and type your response.
486+~some-urbit= Hello! How are you?
487+~your-urbit:talk= ; Well, thanks!
493+~your-urbit=^ Well, thanks!
496+#### Activating Lines
498+A line number identifying the **subsequent** line is displayed every 5
503+~your-urbit= This is my message.
504+~your-urbit= This is another message.
505+~your-urbit sends a message.
506+~your-urbit/ http://example.com/
507+~your-urbit# (add 2 2)
510+~your-urbit=^ That's my message!
513+You can use a line number to **activate** a line:
519+which prints the number, line identifier, timestamp, sender, audience,
524+0v3.hl51p.jhege.amhec.vb37r.3rejr at ~2016.6.24..04.48.21..a235
525+~your-urbit to ~another-urbit
526+in reply to: ~your-urbit:
527+> This is my message.
531+If information got truncated — like what happens for long URLs or expressions,
532+or if there's additional information available — as is the case with
533+replies and attachments (e.g. stack traces) — activating the message will show
536+You can also activate the most recent line with `;`, the second-most recent
537+with `;;`, and so on.
539+### Creating and managing circles
541+As mentioned before, any urbit can host any number of circles. Existing circles
542+can be deleted or modified with various commands. All commands in this section
543+shoild be sent from the `talk>` prompt.
547+Syntax: `;create [type] %name 'description'`
549+Creates and joins a circle, where `[type]` is any of the following:
550+- `channel`: public circle. Has a blacklist for write control.
551+- `village`: invite-only circle.
552+- `journal`: publicly readable, invite-only for writing.
553+- `mailbox`: publicly writeable, can only be read by its host.
555+Let's create an example mailbox:
558+sampel-palnet:talk> ;create mailbox %coolbox 'cool messages only'
561+Something like this should print:
564+--------------| ;create mailbox %coolbox 'cool messages only'
565+--------------| :: onn %coolbox
566+--------------| bound '>' {[hos=~sampel-palnet nom=%coolbox]}
567+--------------| %coolbox: see ~sampel-palnet hear
568+--------------| new > %coolbox
569+--------------| %coolbox: cap: cool messages only
570+--------------| %coolbox: fit: caps:Y unic:â
575+Syntax: `;delete %name 'optional reason'`
577+Deletes a circle. If a reason is specified, that gets sent to all
578+subscribers before the circle gets deleted.
580+To delete our example above:
583+sampel-palnet:talk> ;delete %coolbox 'people sent uncool messages'
586+#### Change Description
588+Syntax: `;depict %name 'description'`
590+Changes the description of an existing circle `%name`.
595+sampel-palnet:talk> ;depict %coolbox 'cool messages only. NO EXCEPTIONS.'
601+Syntax: `;filter %name [capitals] [unicode]`
603+Configures the message filter for circle `%name`: whether to allow
604+capital and/or unicode characters. `y`/`&`/`true` for allowed,
605+`n`/`|`/`false` for disallowed.
607+So, to allow capital letters and disallow unicode in the circle `%coolbox`:
610+sampel-palnet:talk> ;filter %coolbox & |
614+sampel-palnet:talk> ;filter %coolbox y n
617+And we get the output:
620+--------------| ;filter %coolbox & |
621+--------------| %coolbox: fit: caps:Y unic:n
626+Syntax: `;invite %name ~someone`
628+Invites someone into your circle `%name`. If they were previously banished,
629+removes them from the blacklist.
630+Can also invite multiple ships at once, `~comma, ~separated`.
635+~sampel-palnet:talk> ;invite %coolbox ~lodleb-ritrul
640+Syntax: `;banish %name ~someone`
642+Removes someone from your circle `%name`. If they were previously invited,
643+removes them from the whitelist.
644+Can also banish multiple ships at once, `~comma, ~separated`.
648+Syntax: `;source %name ~other/circle`
650+Adds `~other/circle` as a source for circle `%name`. This causes all
651+messages sent to `~other/circle` to also appear in `%name`.
656+~sampel-palnet:talk> ;source %coolbox ~marzod/urbit-help
661+Syntax: `;unsource %name ~other/circle`
663+Removes `~other/circle` as a source for circle `%name`.
668+~sampel-palnet:talk> ;unsource %coolbox ~marzod/urbit-help
671+#### Circle Membership
673+If you have joined a circle, you can make this information publicly
674+available to help others find that circle as well.
678+Syntax: `;show ~some/circle`
680+Adds a circle to your public membership list on your Hall profile. Hall profiles
685+Syntax: `;hide ~some/circle`
687+Removes a circle from your public membership list on your Hall profile. Hall
688+profiles are not used yet.
692+You'll see status notifications when people enter or leave circles you're
695+#### Notifications Off
699+Turn off status (and config) notifications.
701+#### Notifications On
703+Syntax: `;unset quiet`
705+Turn on status (and config) notifications.
711+List everyone in all your subscribed circles. Optionally specify a
712+specific circle to list members of just those: `;who ~some/circle`
717+~sampel-palnet:talk> ;who ~marzod/urbit-help
722+Syntax: `;attend ~some/circle [presence]`
724+Manually set your presence to show up as one of the following. (In the
725+future, a sufficiently advanced client can automatically set these for
731+- `gone` - not present
736+~sampel-palnet:talk> ;attend ~marzod/urbit-help idle
739+#### Set Display Name
741+Syntax: `;name ~some/circle 'my handle'`
743+Set a handle ("name") for yourself in a specific circle. It will display
744+to users who have done `;set nicks`, but gets truncated if it's longer
749+An audience consists of one or more messaging targets. These can be
750+circles or ships. (In the latter case, it's secretly the `~ship/inbox`
755+Glyphs are found at the end of your prompt to as a quick indicator of where
756+your messages will be sent.
758+Glyphs are assigned by circle hash out of the following list:
761+> = + - } ) , . " ' ^ $ % & @
764+Alphanumeric characters and `|#;:*~_` are reserved; all others (the
765+above list, and `\/!?({<`) can be manually assigned.
767+For example, `-` the glyph at the end of the prompt below might indicates that
768+messages sent from this prompt will go to some circle with that glyph:
774+To see what circle is bound to a glyph, use the `;what` command followed by the
775+glyph in question, or use `;what` without specifying a glyph to see all of your
776+subscriptions which are bound to glyphs. For example, to see `=`:
779+~sampel-palnet:talk> ;what =
783+To see all of your glyph-bound subscriptions:
786+~sampel-palnet:talk> ;what
787+> ~paldev/numismatic-forum
788+. ~middev/ny-martians
792+Not every audience has a glyph, however. When the audience doesn't have a glyph,
793+such as in the case of direct-messaging a ship, we see their name at the end of
794+the prompt instead. Here we're talking directly to `~dannum-mitryl`:
797+~sampel-palnet:talk[~dannum-mitryl]
802+Syntax: `;bind [glyph] /circle-name`
804+Assigns the chosen glyph to a circle owned by your ship.
809+~sampel-palnet:talk> ;bind + /my-circle
814+Syntax: `;unbind [glyph] /circle-name`
816+Unassigns the chosen glyph from a circle owned by your ship.
821+~sampel-palnet:talk> ;unbind + /my-circle
826+Received posts are prefixed with a glyph to let you know what the
827+audience is. You can activate an individual post to see the full
830+There are a few special-purpose glyphs:
832+- `|` - Informational messages
833+- `:` - Posts directly to you
834+- `;` - Posts to you and others (a multiparty conversation)
835+- `*` - Posts to a complex audience that doesn't directly include you.
844+Set audience to `~ship/circle`.
846+#### Set Audience by Glyph
850+Set audience to the circle previously bound to the chosen glyph.
852+#### Set Audience to Ship
856+Set audience to another ship.
858+#### Set Audience to Own Circle
862+Set audience to a circle on your own ship
864+#### Set Audience + Send Message
866+Syntax: `;~dannum-mitryl this is a private message`
868+Set the audience and send a post in the same line. This works for all of the
869+above audience commands.
871+Your audience is configured with regard to the following rules (in order):
873+- if you manually set the audience, that audience.
874+- if you activated a post, the post you activated.
875+- audience of the last post sent.
883+List all local nicknames.
887+Syntax: `;nick ~some-urbit`
889+Look up a nickname using the known ship-name.
891+#### Reverse Find Nickname
893+syntax: `;nick plato`
895+Find a ship's name using its nickname.
899+Syntax: `;nick ~some-urbit plato`
901+Create a new nickname.
905+Syntax: `;nick ~some-urbit ~`
907+Clear an assigned nickname.
909+#### Display Nicks, Not Ship-Names
913+Show nicknames instead of ship-names. If no local nickname is set, uses
914+that user's handle. If the user has no handle, just the urbit name.
916+#### Display Ship-Names, Not Nicks
918+Syntax: `;unset nicks`
920+Show ship-names instead of nicknames.
922+Nicknames and handles longer than 14 character will be truncated in
923+output. Nicknames are strictly local - like the names on entries in a
926+### Miscellaneous configuration
930+Syntax: `;set showtime`
932+Show the timestamp for each message.
936+Syntax: `;unset showtime`
938+Stop showing the timestamp for each message.
940+#### Change Time Zone
942+Syntax: `;set timezone [+/-][hours]`
944+Adjust the display of the timestamps to a specific timezone. Relative to UTC.
946+#### Sound Notification On
948+Syntax: `;set notify`
950+Emit a terminal bell sound if your six-syllable ship name is mentioned in
953+#### Sound Notification Off
955+Syntax `;unset notify`
957+Do not notify when your ship name is mentioned.
961+Syntax: `;set width [number]`
963+Set the rendering width of `:talk` to a specific number of characters.
967+## Shell {#using-the-shell}
969+The Dojo is our shell; it processes system commands and returns output. It's a
970+good place to quickly experiment with Urbit. On the surface the Dojo is just a
971+Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
977+You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
982+Evaluate a Hoon expression (whitespace matters):
985+~your-urbit:dojo> (add 2 2)
986+~your-urbit:dojo> %+ add 2 2
989+Tall-form Hoon may require multiple lines:
992+~your-urbit:dojo> %+ add
997+Hoon uses something called [the subject](@/docs/learn/hoon/hoon-tutorial/the-subject-and-its-legs.md).
998+The Dojo has its own subject, and that's where Hoon's equivalent of variables,
999+called faces, are stored.
1001+Use `=var` to save faces to the Dojo subject.
1004+~your-urbit:dojo> =foo (add 2 2)
1007+Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
1008+face in a `.hoon` file in this way.
1010+#### System Commands
1012+Use `=dir` to set the current working directory:
1015+~your-urbit:dojo> =dir %/web
1018+(`%` represents your current directory. For a complete explanation on urbit
1019+paths, see the [filesystem section](@/docs/using/filesystem.md))
1021+Generators (files in `/gen`) are run with `+`:
1024+~your-urbit:dojo> +hello 'world'
1027+Save output to a file in `%clay` with `*`:
1030+~your-urbit:dojo> *some/file/path/hoon 'hello world'
1033+Run system commands from `:hood`, like `reload`, using `|`:
1036+~your-urbit:dojo> |reload %eyre
1041+Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
1042+directory. Many Dojo commands exist in the form of generators. The syntax for
1043+running a generator is `+genname` for a generator saved as `genname.hoon`.
1047+Accepts a path and displays the file. Similar to Unix `cat`.
1050+~your-urbit:dojo> +cat %/gen/curl/hoon
1055+Generates a code that is used to remotely log into your ship. No
1059+~your-urbit:dojo> +code
1064+Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.
1067+~your-urbit:dojo> +curl "http://nyt.com"
1072+Just prints the argument. Accepts a `@ta`.
1075+~your-urbit:dojo> +hello 'mars'
1080+Similar to Unix `ls`. Accepts a path.
1083+~your-urbit:dojo> +ls %/web
1084+~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
1089+Generates a random moon from a planet. No arguments.
1092+~your-urbit:dojo> +moon
1097+Compile the current state of the kernel and output a
1098+noun. Usually downloaded to a file in unix. No arguments.
1101+~your-urbit:dojo> .urbit/pill +solid
1106+Testrunner. Can test multiple generators at once, conventionally ones
1107+in the `/test` folder. Takes a path.
1110+~your-urbit:dojo> +test /lib
1115+Generate a ticket for an urbit ship. Takes an urbit name (`@p`).
1119+~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
1124+Generate a recursive directory listing. Takes a path.
1127+~your-urbit:dojo> +tree %/web
1132+The hood is the system daemon. See `gen/hood` and `app/hood`.
1134+`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
1135+an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
1138+~your-urbit:dojo> |hi ~binzod "you there?"
1141+`|link` / `|unlink` - Link / unlink a remote app. Accepts an
1142+Urbit name and an app name.
1145+~your-urbit:dojo> |link ~talsur-todres %octo
1148+`|mass` - Prints the current memory usage of all the kernel modules.
1152+~your-urbit:dojo> |mass
1155+`|reload` - Reloads a kernel module (vane) from source. Accepts any
1156+number of vane names.
1159+~your-urbit:dojo> |reload %clay %eyre
1162+`|reset` - Reloads `hoon.hoon` and all modules. No arguments.
1165+~your-urbit:dojo> |reset
1168+`|start` - Starts an app. Accepts an app name.
1171+~your-urbit:dojo> |start %curl
1178+#### Sources and sinks
1180+A Dojo command is either a **source** or a **sink**. A source is just something
1181+that can be printed to your console or the result of some computation. A
1182+sink is an **effect**: a change to the filesystem, a network message, a
1183+change to your environment, or typed message to an app.
1185+Sources can be chained together, but we can only produce one effect per
1190+#### `=` - Set variable
1192+Set any environment variable:
1195+~your-urbit:dojo> =foo 42
1196+~your-urbit:dojo> (add 2 foo)
1201+Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
1202+variable in a `.hoon` file in this way.
1204+#### Special Variables
1206+There are a few special variables that the Dojo maintains.
1208+#### `:` - Send to app
1210+`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
1212+Send a `helm-hi` message to `hood`:
1215+~your-urbit:dojo> :hood &helm-hi 'hi'
1218+Apps usually expect marked data, so `&` is often used here.
1220+#### `*` - Save in `%clay`
1222+Save a new `.udon` ([Udon](@/docs/using/sail-and-udon.md)) file in `web`:
1225+~your-urbit:dojo> *%/web/foo/udon '# hello'
1228+The last component of the path is expected to be the mark (or mime
1231+#### `.` - Export to Unix
1233+Export a noun to Unix with `.`:
1236+~your-urbit:dojo> .foo/bar/baz (add 2 2)
1239+Which creates a file at `pier/.urb/put/foo/bar.baz`.
1241+This is very often used with `+solid`:
1244+~your-urbit:dojo> .urbit/pill +solid
1247+Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
1251+#### `&` - Mark conversion
1253+Convert between marks using `&`, with the destination mark first. You can stack multiple mark conversions together, and some marks can only be converted to specific other marks. In this example, [Udon](@/docs/using/sail-and-udon.md#udon) is converted to `&hymn` (a mark which supplies the `html`, `head`, `body` and closing tags) first, before being converted to HTML:
1256+~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
1257+'<html><head></head><body><h1 id="hello">hello</h1></body></html>'
1260+Performing a conversion straight from Udon to the `&hymn` mark reveals a bit more about its mark conversion:
1263+~your-urbit:dojo>&hymn &udon ';h1#hello: hello'
1264+[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]
1267+As does converting straight from Udon to HTML:
1270+~your-urbit:dojo>&html &udon ';h1#hello: hello'
1274+#### `_` - Run a function
1276+Use `_` to run a gate (or function):
1278+Write an arbitrary function and pass data to it:
1281+~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
1285+Use a function to get the status code from an http request:
1288+~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
1292+#### `+` `-` - HTTP requests
1294+`+http[s]://example.com` - sends a GET request
1296+`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
1297+JSON `"hi"` in the body.
1299+`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
1300+JSON `"hi"` in the body.
1302+Note that the first of these is a source while the last two are sinks.
1304+#### `+` - Generators
1306+Generators are simple Hoon scripts loaded from the filesystem. They live
1309+An example of a generator that is built into your urbit is `+code`. It produces
1310+the code needed to log into your ship remotely.
1313+~your-urbit:dojo> +code
1314+fintyr-haldet-fassev-solhex
1319+You can use `=` to set an environment variable in Dojo, but there are
1320+a few reserved names that have special uses.
1324+Current working `%clay` desk and revision. Read / write.
1329+~your-urbit:dojo> =dir %/web
1330+~your-urbit:dojo> +ls %
1331+404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
1336+Current set of libraries (`/lib`) in your environment. Can be set
1337+with `/+`. Read / write.
1342+~your-urbit:dojo> /+ number-to-words
1344+Now we can use arms from lib/number-to-words.hoon
1346+~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)
1351+Current set of structures (`/sur`) in your environment. Can be set
1352+with `/-`. Read / write.
1357+~your-urbit:dojo> /- sole
1359+Now we can use arms in sur/sole.hoon.
1361+~your-urbit:dojo> `sole-effect:sole`[%bel ~]
1366+The current (128-bit `@da`) time. Read-only.
1371+~your-urbit:dojo> now
1372+~2016.3.21..21.10.57..429a
1377+The current urbit ship. Read-only.
1382+~your-urbit:dojo> our
1388+512 bits of entropy. Read-only.
1393+~your-urbit:dojo> eny
1394+\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
1395+ 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
1401+If you encounter `%dy-edit-busy` while entering commands, it is
1402+because your Dojo is blocked on a timer or an HTTP request. Type backspace
1403+and your Dojo will end the blocked command.
1406+## Filesystem {#filesystem}
1408+Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
1409+referentially transparent namespace. An easy way to think about it is like typed
1412+The most common way to use Clay is to mount a Clay node in a Unix directory. The mounted directory is always at the root of your
1417+This quick-start guide will walk you through some common commands. Follow along
1418+using your Dojo. When you get a `>=` message after entering a command, this means
1419+that the command was successful.
1421+When developing it's a good idea to use a separate desk. Create a `%sandbox`
1422+desk based on the `%home` desk:
1425+~your-urbit:dojo> |merge %sandbox ~your-urbit %home
1428+Running `our` produces your ship-name, meaning that you can run the following
1429+command instead of typing out the entire thing. Useful for comets, due to their
1433+~your-urbit:dojo> |merge %sandbox our %home
1436+Most of the time we want to use Clay from Unix. Mount the entire contents of
1437+your `sandbox` desk to Unix:
1440+~your-urbit:dojo> |mount /=sandbox=
1443+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
1444+displays files in the current directory, and `+cat` displays the contents of
1447+We can use `%` to mean "current directory." The result of the command below
1448+is just like using `ls` in a Unix terminal.
1451+~your-urbit:dojo> +ls %
1454+Notice how `+cat %` does the same thing. That's because everything in Clay,
1455+including directories, is a file.
1457+Let's explore the `/web` directory of the `%sandbox` desk.
1460+~your-urbit:dojo> +ls /=sandbox=/web
1463+Let's see the contents of `/=sandbox=/web/404/hoon`:
1466+~your-urbit:dojo> +cat /=sandbox=/web/404/hoon
1469+Now let's navigate to `/web` on `%sandbox` using `=dir`, which is like `cd` in Unix.
1472+~your-urbit:dojo> =dir /=sandbox=/web
1475+You'll notice that your prompt is now
1476+`~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web>`.
1479+~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> +ls %
1482+To change back to our home directory, we use `=dir` without any path.
1485+~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> =dir
1488+Sync from your friend `~some-ship`'s `%experiment` desk to your
1492+~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
1495+If and when your sync is successful, you will receive a message:
1498+activated sync from %experiment on ~some-ship to %sandbox
1501+The ship that you sync from will get their own message indicating that you're
1502+both connected as peers:
1505+; ~your-urbit is your neighbor.
1514+A path in Clay is a list of URL-safe text, restricted to the characters
1515+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
1516+meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
1517+In other words, paths are expressed as `/foo/bar/baz`. File extensions are
1518+separated from file names with `/`, not `.`. Extensions are syntactically
1519+identical to subdirectories, except that they must terminate the path.
1521+Paths begin with a piece of data called a `beak`. A beak is formally a
1522+`(p=ship q=desk r=case)`; it has three components, and might look like
1523+`/~dozbud-namsep/home/11`.
1525+The first `beak` component is `ship`, which is, as you might guess, the name of
1526+an Urbit ship. The second component is `desk`, which is a workspace meant to
1527+contain other directories; the default desk is `%home`. The third component is
1528+`case`, which represents version information in various ways: date and time;
1529+a version sequence, which is a value incremented by one whenever a file on the
1530+given `desk` is modified; or an arbitrary plaintext label.
1532+You can find what your `beak` is at any given moment by
1533+typing `%` in the Dojo and looking at the first three results.
1535+We use `beak`s because, unlike the current internet, the Urbit network uses a
1536+global namespace. That means that a file named `example.hoon` in the `/gen`
1537+directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
1538+universal address to anyone else on the network:
1539+`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
1540+course, doesn't mean that everyone on the network has privileges to access that
1543+The structure that combines a `beak` with further path information is called a
1548+The `%` command, which we gestured at in the above section, represents the
1549+**relative path**, which is the path where you are currently working. If your
1550+working directory is just your home desk, indicated by the
1551+prompt `~your-planet:dojo>`, then running the command below will print your
1552+working directory's `beam` information: your `beak`, and a `~` that represents
1553+the empty list since no path is present.
1559+`%`s can be stacked to indicate one level further up in the hierarchy for each
1560+additional `%`. Try the following command:
1563+~your-planet:dojo> %%%
1566+You'll probably notice that it only has your ship name and the empty list. The
1567+two additional `%`s abandoned the `case` and the `desk` information by moving
1568+up twice the hierarchy.
1570+There are no local relative paths. `/foo/bar` must be written as
1575+You don't need to write out the explicit path every time you want to reference
1576+somewhere outside of your working directory. You can substitute `=` for the
1579+Recall that a full address in the the Urbit namespace is a `beam`: the
1580+`/ship/desk/case/path`. If you've switched to another desk before, you're
1581+already familiar with substitution syntax:
1584+~your-urbit:dojo> =dir /=sandbox=
1587+The above command substitutes uses substitution to use your current `ship` and
1588+`case`; only the `desk` argument, which is located between the other two, is
1589+given something new. Without substitution, you would need to write:
1592+~your-urbit:dojo> =dir /~your-urbit/home/85
1595+Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
1596+paths. For example, if you are in the `/gen` directory, you can reference a file
1597+in the `/app` directory like below. (`+cat` displays the contents of a file).
1600+~your-urbit:dojo> =dir %/gen
1601+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
1604+Note what was substituted out, and note that we don't need to separate `=` with
1607+If we changed our working directory to something called `/gen/gmail`, we could
1608+access a file called
1611+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
1612+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
1615+Because both paths share a directory named `/gmail` at the same position in the
1616+address hierarchy -- which, if you recall, is just a `list` -- the above command
1619+We can do the same thing between desks. If `%sandbox` has been merged with
1620+`%home`, the following command will produce the same results as the above
1624+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
1627+Most commonly this is used to avoid having to know the current revision
1628+number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
1630+#### Changing directories
1632+Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
1634+For example, the syntax to navigate to `/home/gen/ask` is:
1637+~your-urbit:dojo> =dir /=home=/gen/ask
1640+This command will turn your prompt into something like this:
1643+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
1646+Using `=dir` without anything else uses the null path, which returns you to
1650+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
1653+Your dojo prompt will turn back into `~your-urbit:dojo>`.
1655+To go up levels in the path hierarchy, recall the relative path expression
1656+`%`. Stacking them represents another level higher in the hierarchy than
1657+the current working directory for each `%` beyond the initial. The command below
1658+brings you one level up:
1661+~your-urbit:dojo> =dir %/gen
1662+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
1665+### Revision-control
1669+Syntax: `|mount /clay/path [Unix-name]`
1671+Mount the `clay-path` at the Unix mount point `Unix-name`.
1679+Mounts `%/web` to `/web` inside your pier directory.
1682+|mount %/gen generators
1685+Mounts `%/gen` to `/generators` inside your pier directory.
1690+|unmount [clay-path || Unix-name]
1693+Unmount the path or name from Unix.
1701+Unmounts the path `%/web` from whatever name it was mounted as.
1704+|unmount %generators
1707+Unmounts the Unix path `/generators`.
1712+|merge desk beak[, =gem strategy]
1715+Merges a `beak` into a `desk` using an optional merge `strategy`.
1717+A `beak` is a ship-desk-case triple, encoded as a
1718+path(`/~dozbud/home/2`)
1723+|merge %home-work /=home=, =gem %fine
1726+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
1729+|merge %examples ~wacbex-ribmex %examples
1732+Merge the `%examples` desk from `~waxbex-ribmex`
1737+|sync desk plot [plot-desk]
1740+Subscribe to continuous updates from remote `plot` on local `desk`.
1741+`plot-desk` can specify the remote `desk` name. When omitted it is
1742+defaulted to being the same as `desk`. Non-comet urbits have
1743+`|sync %home ~parent %kids` automatically set up (where `~parent` is the
1744+planet that issued a moon, the star that issued a planet, or the galaxy
1745+that issued a star).
1750+|sync %home-local ~dozbud %home
1758+|unsync desk plot [plot-desk]
1761+Unsubscribe from updates from remote `plot` on local `desk` with
1762+optional `plot-desk`. Arguments must match original `|sync` command.
1767+|unsync %home-local ~dozbud %home
1776+Label the current version of `desk` `name`.
1781+|label %home release
1784+### Merge strategies
1786+`%init` - Used if it's the first commit to a desk. Also can be used to
1787+"reinitialize" a desk -- revision numbers keep going up, but the new
1788+revision isn't necessarily a descendent of the previously numbered
1789+version, allowing merges to be rerun.
1791+`%this` - Keep what's in Bob's desk, but join the ancestry.
1793+`%that` - take what's in Alice's desk, but join the ancestry. This is
1794+the reverse of `%this`. This is different from `%init` because the new
1795+commit has both sides in its ancestry.
1797+`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
1798+ancestry of the other.
1800+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
1801+use as our merge base.
1803+A `%meet` merge only succeeds if the changes from the merge base to
1804+Alice's head (hereafter, "Alice's changes") are in different files than
1805+Bob's changes. In this case, the parents are both Alice's and Bob's
1806+heads, and the data is the merge base plus Alice's changed files plus
1807+Bob's changed files.
1809+A `%mate` merge attempts to merge changes to the same file when both
1810+Alice and Bob change it. If the merge is clean, we use it; otherwise, we
1811+fail. A merge between different types of changes -- for example,
1812+deleting a file vs changing it -- is always a conflict. If we succeed,
1813+the parents are both Alice's and Bob's heads, and the data is the merge
1814+base plus Alice's changed files plus Bob's changed files plus the merged
1817+A `%meld` merge will succeed even if there are conflicts. If there are
1818+conflicts in a file, then we use the merge base's version of that file,
1819+and we produce a set of files with conflicts. The parents are both
1820+Alice's and Bob's heads, and the data is the merge base plus Alice's
1821+changed files plus Bob's changed files plus the successfully merged
1822+files plus the merge base's version of the conflicting files.
1824+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
1825+doesn't we use an `%init` merge. Otherwise, we progressively try
1826+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
1827+merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
1828+the scratch desk with the `%meld` option to force the merge. Finally, we
1829+annotate any conflicts, if we know how.
1835+Syntax: `+cat path [path ...]`
1837+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
1838+contents. If that `path` is a file, the contents of the file is printed. If the
1839+`path` terminates in a directory, the list of names at that path is produced.
1845+Similar to Unix `ls`. `+ls` takes a single `path`.
1847+Produces a list of names at the `path`.
1850+~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
1857+Remove the data at `path`. `path` must be a path to actual node, not a
1862+Syntax: `|cp to from`
1864+Copy the file at `from` into the path `to`.
1868+Syntax: `|mv to from`
1870+Move the file at `from` into the path `to`.
1872+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
1873+doesn't happen unless the `|cp` succeeds.