@@ -0,0 +1,1412 @@
1++++
2+title = "Using Your Ship"
3+description = "How to operate your ship, including using your ship's filesystem and messaging applications, starting a moon, or requesting a DNS proxy."
4+template = "page_indiced.html"
5+weight = 2
6+aliases = ["docs/using/arvo-network-dns/", "docs/using/messaging/", "docs/using/shell/", "docs/using/admin/"]
7++++
8+
9+## DNS proxying {#dns-proxying}
10+
11+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.
12+
13+Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
14+
15+### Planets and Stars
16+
17+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.
18+
19+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.
20+
21+To do so, simply run this command in your ship's Dojo:
22+
23+```
24+> :dns|request
25+```
26+
27+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:
28+
29+```
30+> :dns|request .1.2.3.4
31+```
32+
33+`: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 `:chat-cli`; 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 `:chat-cli` message saying `awaiting response from ~zod`.
34+
35+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 set up, `~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`.
36+
37+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
38+
39+### Galaxies
40+
41+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.
42+
43+There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
44+
45+```
46+> :dns|auto
47+```
48+
49+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 `~`.
50+
51+Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, Chat messages, and so on.
52+
53+### More information
54+
55+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 `:chat-cli` 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.
56+
57+The built-in logic for listening on port 80 is 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).
58+
59+
60+Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.
61+
62+### Shutdown
63+
64+You can turn your urbit off with `Ctrl-d` from the Chat or Dojo prompts.
65+
66+You can force-quit your urbit with `Ctrl-z` from anywhere.
67+
68+### Restart
69+
70+To restart your urbit simply pass the name of your pier:
71+
72+```sh
73+$ ./urbit some-planet
74+```
75+
76+or
77+
78+```sh
79+$ ./urbit comet
80+```
81+
82+### Logging
83+
84+To log an urbit's command line output to a file, use `script`:
85+
86+```sh
87+$ script urbit.log ./urbit your-urbit
88+```
89+
90+### Moving your pier
91+
92+Piers are designed to be portable, but it _must_ be done while the urbit
93+is not running. Urbit networking is stateful, so you can't run two copies
94+of the same urbit in two places.
95+
96+To move a pier, simply move the contents of the directory it lives in.
97+To keep these files as small as possible we usually use the `--sparse`
98+option in `tar`. With a pier `your-urbit/`, something like this should work:
99+
100+```sh
101+tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
102+scp your-old-server:~/your-urbit.tar.gz your-new-server:~
103+```
104+
105+Then to unzip it, on your other Unix server, run:
106+
107+```sh
108+tar xfvz your-urbit.tar.gz
109+```
110+
111+Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:
112+
113+```sh
114+./urbit your-urbit
115+```
116+
117+### Console
118+
119+Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.
120+
121+In the CLI, Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no Dojo command or Hoon expression that starts with ')', the Dojo rejects it.
122+
123+`Ctrl-x` - Switches the prompt between running console apps
124+
125+`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack
126+trace.
127+
128+`Ctrl-d` - From Chat or Dojo, stops your Urbit process.
129+
130+`Ctrl-z` - Stops the Urbit process from _anywhere_.
131+
132+`↑` / `↓` - History navigation
133+
134+The following emacs-style key bindings are available:
135+
136+```
137+Ctrl-a Cursor to beginning of the line (Home)
138+Ctrl-b Cursor one character backward (left-arrow)
139+Ctrl-e Cursor to the end of the line (End)
140+Ctrl-f Cursor one character forward (right-arrow)
141+Ctrl-g Beep; cancel reverse-search
142+Ctrl-k Kill to end of line
143+Ctrl-l Clear the screen
144+Ctrl-n Next line in history (down-arrow)
145+Ctrl-p Previous line in history (up-arrow)
146+Ctrl-r Reverse-search
147+Ctrl-t Transpose characters
148+Ctrl-u Kill to beginning of line
149+Ctrl-y Yank from kill buffer
150+```
151+
152+### Landscape
153+
154+On startup Urbit tries to bind to `localhost:80`. If you're already running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-proxying).
155+
156+Once running, you can sign into Landscape, your ship’s web interface, from `http://localhost` or `https://your-urbit.arvo.network`. Since our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.
157+
158+### Moons {#moons}
159+
160+Planets can spawn moons, which are meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
161+
162+To generate a random moon from your planet, run:
163+
164+```
165+~sampel-palnet:dojo> +moon
166+moon: ~faswep-navred-sampel-palnet
167+\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
168+ .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
169+ x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
170+\/ \/
171+```
172+
173+You must manually edit the output of `+moon` to get the correct format for the `<key>`:
174+
175+- strip out the `\/`
176+
177+- combine into one line, omitting spaces
178+
179+- trim the leading `~.`
180+
181+`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
182+in this example.
183+
184+Put `<key>` in a file and that file becomes `<keyfile>`.
185+
186+Another way of generating `<keyfile>` is:
187+
188+```
189+~sampel-palnet:dojo> @moon/key +moon
190+moon: ~faswep-navred-sampel-palnet
191+```
192+
193+`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key` and does not need editing to be used with the `-k` option.
194+
195+You can use the resulting output in the same installation flow from the [Installing Urbit](@/using/install.md) guide, following the same scheme as for booting a planet. That scheme is:
196+
197+```sh
198+$ ./urbit -w <moonname> -G <key> -c <piername>
199+```
200+
201+or
202+
203+```sh
204+$ ./urbit -w <moonname> -k <keyfile> -c <piername>
205+```
206+
207+The `-c <piername>` argument is not required, but it is recommended; otherwise,
208+the resulting directory is a rather unwieldy moon name.
209+
210+Here's how an example moon might be booted:
211+
212+```sh
213+$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
214+```
215+
216+or
217+
218+```sh
219+$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
220+```
221+
222+Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
223+
224+### Continuity breaches
225+
226+While the Urbit network is in this alpha state, we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.
227+
228+Because Urbit networking is stateful we call this a _continuity breach_. Everything has to be restarted from scratch. Your pier will continue to function after we have breached, but it won’t connect to the rest of the Urbit network.
229+
230+When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).
231+
232+## Messaging {#messaging}
233+
234+Let’s get started using the `:chat-cli` application, also known more simply as _Chat_. It's the simplest way to talk to people using the command line interface.
235+
236+### Quickstart
237+
238+The most common uses of `:chat-cli` right now are communicating over a public chat channel on `~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.
239+
240+There are two ways of using `:chat-cli`: from the terminal running the Urbit process, or through the Landscape web UI available from your ship’s URL address, mentioned earlier in this guide.
241+
242+### Joining a chat
243+
244+In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four types of chats: the _channel_ (public with blacklist), _village_ (private with whitelist), the _journal_ (publicly readable, privately writable), and the _mailbox_ (privately readable, publicly writable). But 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](#messaging-manual) section later on.
245+
246+Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
247+
248+Then:
249+
250+```
251+~your-urbit:chat-cli> ;join ~dopzod/urbit-help
252+```
253+
254+Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed. You c
255+
256+Post a line to `~dopzod/urbit-help:`
257+
258+```
259+~your-urbit:chat-cli= Hello, world!
260+```
261+
262+You'll see your message printed below messages from others that came before it. You can always type `;chats` in the `chat-cli` prompt to list all the chats you're in:
263+
264+
265+
266+Glyphs will be automatically assigned to channels, but have the option of binding a glyph (single non-alphanumeric character) to the channel you're joining; the syntax is in the form of `;join ~dopzod/books +`. The chosen glyph will be the symbol that ends your prompt, and it will be what you use as a shortcut to switch to this channel.
267+
268+```
269+~your-urbit:chat-cli= ;+
270+~your-urbit:chat-cli+
271+```
272+
273+Use `;leave` to unsubscribe from a channel:
274+
275+```
276+~your-urbit:chat-cli= ;leave ~dopzod/urbit-help
277+```
278+
279+Now, let's create a channel we can invite some friends to:
280+
281+```
282+~your-urbit:chat-cli= ;create channel /my-channel
283+```
284+
285+Now you can tell your friends to `;join ~your-urbit/my-channel`.
286+
287+### Direct messaging
288+
289+To send a direct message to someone, first set your audience:
290+
291+```
292+~your-urbit:chat-cli= ;~talsur-todres
293+```
294+
295+You'll see your prompt change:
296+
297+```
298+~your-urbit:chat-cli[~talsur-todres]
299+```
300+
301+Now you and `~talsur-todres` can exchange messages directly.
302+
303+```
304+~your-urbit:chat-cli[~talsur-todres] Hey buddy!
305+```
306+
307+To set your audience back to `~dopzod/urbit-help`:
308+
309+```
310+~your-urbit:chat-cli[~talsur-todres] ;~dopzod/urbit-help
311+```
312+
313+You'll see your prompt change back:
314+
315+```
316+~your-urbit:chat-cli=
317+```
318+
319+#### Hoon
320+
321+You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.
322+
323+```
324+~your-urbit:chat-cli= #(add 2 2)
325+```
326+
327+will print as
328+
329+```
330+~your-urbit# (add 2 2)
331+4
332+```
333+
334+### Creating and managing chats
335+
336+As mentioned before, any urbit can host any number of chats. Existing chats can be deleted or modified with various commands. All commands in this section should be sent from the `chat-cli>` prompt.
337+
338+#### Create
339+
340+Syntax: `;create [type] /name +`, where `+` represents an optional glyph.
341+
342+Creates and joins a chat, where `[type]` is any of the following:
343+- `channel`: public chat. Has a blacklist for write control.
344+- `village`: invite-only chat.
345+- `journal`: publicly readable, invite-only for writing.
346+- `mailbox`: publicly writeable, can only be read by its host.
347+
348+Let's create an example mailbox:
349+
350+```
351+sampel-palnet:chat-cli> ;create mailbox /coolbox ^
352+```
353+
354+#### Delete
355+
356+Syntax: `;delete /name`
357+
358+Deletes a chat.
359+
360+### Status
361+
362+You'll see status notifications when people enter or leave chats you're subscribed to.
363+
364+#### Notifications off
365+
366+Syntax: `;set quiet`
367+
368+Turn off status (and config) notifications.
369+
370+#### Notifications on
371+
372+Syntax: `;unset quiet`
373+
374+Turn on status (and config) notifications.
375+
376+#### Chat glyphs
377+
378+Glyphs are found at the end of your prompt to as a quick indicator of where
379+your messages will be sent.
380+
381+Glyphs are assigned by chat hash out of the following list:
382+
383+```
384+> = + - } ) , . " ' ^ $ % & @
385+```
386+
387+Alphanumeric characters and `|#;:*~_` are reserved; all others (the
388+above list, and `\/!?({<`) can be manually assigned.
389+
390+For example, `-` the glyph at the end of the prompt below might indicates that
391+messages sent from this prompt will go to some chat with that glyph:
392+
393+```
394+~sampel-palnet:chat-cli-
395+```
396+
397+To see what chat is bound to a glyph, use the `;what` command followed by the
398+glyph in question, or use `;what` without specifying a glyph to see all of your
399+subscriptions which are bound to glyphs. For example, to see `=`:
400+
401+```
402+~sampel-palnet:chat-cli> ;what =
403+~dopzod/urbit-help
404+```
405+
406+To see all of your glyph-bound subscriptions:
407+
408+```
409+~sampel-palnet:chat-cli> ;what
410+> ~paldev/numismatic-forum
411+. ~middev/ny-martians
412+= ~dopzod/urbit-help
413+```
414+
415+Not every audience has a glyph, however. When the audience doesn't have a glyph,
416+such as in the case of direct-messaging a ship, we see their name at the end of
417+the prompt instead. Here we're talking directly to `~dannum-mitryl`:
418+
419+```
420+~sampel-palnet:chat-cli[~dannum-mitryl]
421+```
422+
423+#### Bind
424+
425+Syntax: `;bind [glyph] /chat-name`
426+
427+Assigns the chosen glyph to a chat owned by your ship.
428+
429+For example:
430+
431+```
432+~sampel-palnet:chat-cli> ;bind + /my-chat
433+```
434+
435+#### Unbind
436+
437+Syntax: `;unbind [glyph] /chat-name`
438+
439+Unassigns the chosen glyph from a chat owned by your ship.
440+
441+For example:
442+
443+```
444+~sampel-palnet:chat-cli> ;unbind + /my-chat
445+```
446+
447+#### Prefixes
448+
449+Received posts are prefixed with a glyph to let you know what the
450+audience is. You can activate an individual post to see the full
451+audience.
452+
453+There are a few special-purpose glyphs:
454+
455+- `|` - Informational messages
456+- `:` - Posts directly to you
457+- `;` - Posts to you and others (a multiparty conversation)
458+- `*` - Posts to a complex audience that doesn't directly include you.
459+
460+
461+### Configuration
462+
463+#### Set audience
464+
465+`;~ship/chat`
466+
467+Set audience to `~ship/chat`.
468+
469+#### Set audience by glyph
470+
471+Syntax: `;[glyph]`
472+
473+Set audience to the chat previously bound to the chosen glyph.
474+
475+#### Set audience to ship
476+
477+syntax `;~ship`
478+
479+Set audience to another ship.
480+
481+#### Set audience to own chat
482+
483+Syntax: `;%chat`
484+
485+Set audience to a chat on your own ship.
486+
487+#### Set audience and send message
488+
489+Syntax: `;~dannum-mitryl this is a private message`
490+
491+Set the audience and send a post in the same line. This works for all of the
492+above audience commands.
493+
494+Your audience is configured with regard to the following rules (in order):
495+
496+- if you manually set the audience, that audience.
497+- if you activated a post, the post you activated.
498+- audience of the last post sent.
499+
500+### Miscellaneous configuration
501+
502+#### Show timestamps
503+
504+Syntax: `;set showtime`
505+
506+Show the timestamp for each message. This is set by default.
507+
508+#### Hide timestamps
509+
510+Syntax: `;unset showtime`
511+
512+Stop showing the timestamp for each message.
513+
514+#### Change timezone
515+
516+Syntax: `;set timezone [+/-][hours]`
517+
518+Adjust the display of timestamps to a specific timezone. Relative to UTC.
519+
520+#### Sound notification on
521+
522+Syntax: `;set notify`
523+
524+Emit a terminal bell sound if your six-syllable ship name is mentioned in
525+a message. This is set by default.
526+
527+#### Sound notification off
528+
529+Syntax `;unset notify`
530+
531+Do not notify when your ship name is mentioned.
532+
533+#### Set width
534+
535+Syntax: `;set width [number]`
536+
537+Set the rendering width of `:chat-cli` to a specific number of characters.
538+(Minimum of 30.)
539+
540+
541+## Shell {#using-the-shell}
542+
543+The Dojo is our shell; it processes system commands and returns output. It's a
544+good place to quickly experiment with Urbit. On the surface the Dojo is just a
545+Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
546+data in Urbit.
547+
548+### Quickstart
549+
550+You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
551+commands.
552+
553+#### Math
554+
555+Evaluate a Hoon expression (whitespace matters):
556+
557+```
558+~your-urbit:dojo> (add 2 2)
559+~your-urbit:dojo> %+ add 2 2
560+```
561+
562+Tall-form Hoon may require multiple lines:
563+
564+```
565+~your-urbit:dojo> %+ add
566+~your-urbit:dojo< 2
567+~your-urbit:dojo< 2
568+```
569+
570+Hoon uses something called [the subject](@/docs/tutorials/hoon/the-subject-and-its-legs.md).
571+The Dojo has its own subject and that's where Hoon's equivalent of variables,
572+called faces, are stored.
573+
574+Use `=var` to save faces to the Dojo subject.
575+
576+```
577+~your-urbit:dojo> =foo (add 2 2)
578+```
579+
580+Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
581+face in a `.hoon` file in this way.
582+
583+#### System commands
584+
585+Use `=dir` to set the current working directory:
586+
587+```
588+~your-urbit:dojo> =dir %/gen
589+```
590+
591+(`%` represents your current directory. For a complete explanation on urbit
592+paths, see the [filesystem section](#filesystem).)
593+
594+Generators (files in `/gen`) are run with `+`:
595+
596+```
597+~your-urbit:dojo> +hello 'world'
598+```
599+
600+Save output to a file in `%clay` with `*`:
601+
602+```
603+~your-urbit:dojo> *some/file/path/hoon 'hello world'
604+```
605+
606+Run system commands from `:hood`, like `reload`, using `|`:
607+
608+```
609+~your-urbit:dojo> |reload %eyre
610+```
611+
612+### Generators
613+
614+Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
615+directory. Many Dojo commands exist in the form of generators. The syntax for
616+running a generator is `+genname` for a generator saved as `genname.hoon`.
617+
618+#### `+cat`
619+
620+Accepts a path and displays the file. Similar to Unix `cat`.
621+
622+```
623+~your-urbit:dojo> +cat %/gen/curl/hoon
624+```
625+
626+#### `+code`
627+
628+Generates a code that is used to remotely log into your ship. No
629+arguments.
630+
631+```
632+~your-urbit:dojo> +code
633+```
634+
635+#### `+curl`
636+
637+Retrieves data from a URL. Accepts a `tape`. Similar to Unix `curl`.
638+
639+```
640+~your-urbit:dojo> +curl "http://nyt.com"
641+```
642+
643+#### `+hello`
644+
645+Just prints the argument. Accepts a `@ta`.
646+
647+```
648+~your-urbit:dojo> +hello 'mars'
649+```
650+
651+#### `+ls`
652+
653+Similar to Unix `ls`. Accepts a path.
654+
655+```
656+~your-urbit:dojo> +ls %/gen
657+~your-urbit:dojo> +ls /~talsur-todres/home/2/gen/program
658+```
659+
660+#### `+moon`
661+
662+Generates a random moon from a planet. No arguments.
663+
664+```
665+~your-urbit:dojo> +moon
666+```
667+
668+#### `+solid`
669+
670+Compile the current state of the kernel and output a
671+noun. Usually downloaded to a file in unix. No arguments.
672+
673+```
674+~your-urbit:dojo> .urbit/pill +solid
675+```
676+
677+#### `+test`
678+
679+Testrunner. Can test multiple generators at once, conventionally ones
680+in the `/test` folder. Takes a path.
681+
682+```
683+~your-urbit:dojo> +test /lib
684+```
685+
686+#### `+ticket`
687+
688+Generate a ticket for an urbit ship. Takes an urbit name (`@p`).
689+
690+
691+```
692+~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
693+```
694+
695+#### `+tree`
696+
697+Generate a recursive directory listing. Takes a path.
698+
699+```
700+~your-urbit:dojo> +tree %/sys
701+```
702+
703+### Hood
704+
705+The hood is the system daemon. See `gen/hood` and `app/hood`.
706+
707+`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
708+an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
709+
710+```
711+~your-urbit:dojo> |hi ~binzod "you there?"
712+```
713+
714+`|link` / `|unlink` - Link / unlink a remote app. Accepts an
715+Urbit name and an app name.
716+
717+```
718+~your-urbit:dojo> |link ~talsur-todres %octo
719+```
720+
721+`|mass` - Prints the current memory usage of all the kernel modules.
722+No arguments.
723+
724+```
725+~your-urbit:dojo> |mass
726+```
727+
728+`|reload` - Reloads a kernel module (vane) from source. Accepts any
729+number of vane names.
730+
731+```
732+~your-urbit:dojo> |reload %clay %eyre
733+```
734+
735+`|reset` - Reloads `hoon.hoon` and all modules. No arguments.
736+
737+```
738+~your-urbit:dojo> |reset
739+```
740+
741+`|start` - Starts an app. Accepts an app name.
742+
743+```
744+~your-urbit:dojo> |start %curl
745+```
746+
747+---
748+
749+### Dojo manual
750+
751+#### Sources and sinks
752+
753+A Dojo command is either a **source** or a **sink**. A source is just something
754+that can be printed to your console or the result of some computation. A
755+sink is an **effect**: a change to the filesystem, a network message, a
756+change to your environment, or a typed message to an app.
757+
758+Sources can be chained together, but we can only produce one effect per
759+command.
760+
761+#### Sinks
762+
763+#### `=` - Set variable
764+
765+Set any environment variable:
766+
767+```
768+~your-urbit:dojo> =foo 42
769+~your-urbit:dojo> (add 2 foo)
770+
771+44
772+```
773+
774+Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
775+variable in a `.hoon` file in this way.
776+
777+#### Special variables
778+
779+There are a few special variables that the Dojo maintains.
780+
781+#### `:` - Send to app
782+
783+`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
784+
785+Send a `helm-hi` message to `hood`:
786+
787+```
788+~your-urbit:dojo> :hood &helm-hi 'hi'
789+```
790+
791+Apps usually expect marked data, so `&` is often used here.
792+
793+#### `*` - Save in `%clay`
794+
795+Save a new `.hoon` file in `gen`:
796+
797+```
798+~your-urbit:dojo> *%/gen/foo/hoon '# hello'
799+```
800+
801+The last component of the path is expected to be the mark (or mime
802+type).
803+
804+#### `.` - Export to Unix
805+
806+Export a noun to Unix with `.`:
807+
808+```
809+~your-urbit:dojo> .foo/bar/baz (add 2 2)
810+```
811+
812+Which creates a file at `pier/.urb/put/foo/bar.baz`.
813+
814+This is very often used with `+solid`:
815+
816+```
817+~your-urbit:dojo> .urbit/pill +solid
818+```
819+
820+Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
821+
822+### Sources
823+
824+#### `&` - Mark conversion
825+
826+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/tutorials/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:
827+
828+```
829+~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
830+'<html><head></head><body><h1 id="hello">hello</h1></body></html>'
831+```
832+
833+Performing a conversion straight from Udon to the `&hymn` mark reveals a bit more about its mark conversion:
834+
835+```
836+~your-urbit:dojo>&hymn &udon ';h1#hello: hello'
837+[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]
838+```
839+
840+As does converting straight from Udon to HTML:
841+
842+```
843+~your-urbit:dojo>&html &udon ';h1#hello: hello'
844+';h1#hello: hello'
845+```
846+
847+#### `_` - Run a function
848+
849+Use `_` to run a gate (or function):
850+
851+Write an arbitrary function and pass data to it:
852+
853+```
854+~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
855+9
856+```
857+
858+Use a function to get the status code from an http request:
859+
860+```
861+~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
862+301
863+```
864+
865+#### `+` `-` - HTTP requests
866+
867+`+http[s]://example.com` - sends a GET request
868+
869+`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
870+JSON `"hi"` in the body.
871+
872+`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
873+JSON `"hi"` in the body.
874+
875+Note that the first of these is a source while the last two are sinks.
876+
877+#### `+` - Generators
878+
879+Generators are simple Hoon scripts loaded from the filesystem. They live
880+in `gen/`.
881+
882+An example of a generator that is built into your urbit is `+code`. It produces
883+the code needed to log into your ship remotely.
884+
885+```
886+~your-urbit:dojo> +code
887+fintyr-haldet-fassev-solhex
888+```
889+
890+### Variables
891+
892+You can use `=` to set an environment variable in Dojo, but there are
893+a few reserved names that have special uses.
894+
895+#### `dir`
896+
897+Current working `%clay` desk and revision. Read / write.
898+
899+**Examples:**
900+
901+```
902+~your-urbit:dojo> =dir %/gen
903+~your-urbit:dojo> +ls %
904+404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
905+```
906+
907+#### `lib`
908+
909+Current set of libraries (`/lib`) in your environment. Can be set
910+with `/+`. Read / write.
911+
912+**Examples:**
913+
914+```
915+~your-urbit:dojo> /+ number-to-words
916+```
917+Now we can use arms from lib/number-to-words.hoon
918+```
919+~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)
920+```
921+
922+#### `sur`
923+
924+Current set of structures (`/sur`) in your environment. Can be set
925+with `/-`. Read / write.
926+
927+**Examples:**
928+
929+```
930+~your-urbit:dojo> /- sole
931+```
932+Now we can use arms in sur/sole.hoon.
933+```
934+~your-urbit:dojo> `sole-effect:sole`[%bel ~]
935+```
936+
937+#### `now`
938+
939+The current (128-bit `@da`) time. Read-only.
940+
941+**Example:**
942+
943+```
944+~your-urbit:dojo> now
945+~2016.3.21..21.10.57..429a
946+```
947+
948+#### `our`
949+
950+The current urbit ship. Read-only.
951+
952+**Example:**
953+
954+```
955+~your-urbit:dojo> our
956+~your-urbit
957+```
958+
959+#### `eny`
960+
961+512 bits of entropy. Read-only.
962+
963+**Example:**
964+
965+```
966+~your-urbit:dojo> eny
967+\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
968+ 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
969+\/
970+```
971+
972+### Troubleshooting
973+
974+If you encounter `%dy-edit-busy` while entering commands, it is
975+because your Dojo is blocked on a timer or an HTTP request. Type backspace
976+and your Dojo will end the blocked command.
977+
978+
979+## Filesystem {#filesystem}
980+
981+Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
982+referentially transparent namespace. An easy way to think about it is like typed
983+`git`.
984+
985+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 pier directory.
986+
987+### Quickstart
988+
989+This quick-start guide will walk you through some common commands. Follow along
990+using your Dojo. When you get a `>=` message after entering a command, this means
991+that the command was successful.
992+
993+It's important to note that whenever you want to sync changes from your Unix
994+directory to your ship, you must use the `|commit %desk` command, where `%desk`
995+is the desk that you'd like to sync to.
996+
997+When developing it's a good idea to use a separate desk. Create a `%sandbox`
998+desk based on the `%home` desk:
999+
1000+```
1001+~your-urbit:dojo> |merge %sandbox ~your-urbit %home
1002+```
1003+
1004+Running `our` produces your ship-name, meaning that you can run the following
1005+command instead of typing out the entire thing. Useful for comets due to their
1006+very long names.
1007+
1008+```
1009+~your-urbit:dojo> |merge %sandbox our %home
1010+```
1011+
1012+Most of the time we want to use Clay from Unix. Mount the entire contents of
1013+your `sandbox` desk to Unix:
1014+
1015+```
1016+~your-urbit:dojo> |mount /=sandbox=
1017+```
1018+
1019+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
1020+displays files in the current directory, and `+cat` displays the contents of
1021+a file.
1022+
1023+We can use `%` to mean "current directory." The result of the command below
1024+is just like using `ls` in a Unix terminal.
1025+
1026+```
1027+~your-urbit:dojo> +ls %
1028+```
1029+
1030+Notice how `+cat %` does the same thing. That's because everything in Clay,
1031+including directories, is a file.
1032+
1033+Sync from your friend `~some-ship`'s `%experiment` desk to your
1034+`%sandbox` desk:
1035+
1036+```
1037+~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
1038+```
1039+
1040+If and when your sync is successful, you will receive a message:
1041+
1042+```
1043+activated sync from %experiment on ~some-ship to %sandbox
1044+```
1045+
1046+The ship that you sync from will get their own message indicating that you're
1047+both connected as peers:
1048+
1049+```
1050+; ~your-urbit is your neighbor.
1051+```
1052+
1053+---
1054+
1055+### Clay manual
1056+
1057+#### Paths
1058+
1059+A path in Clay is a list of URL-safe text, restricted to the characters
1060+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
1061+meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
1062+In other words, paths are expressed as `/foo/bar/baz`. File extensions are
1063+separated from file names with `/`, not `.`. Extensions are syntactically
1064+identical to subdirectories, except that they must terminate the path.
1065+
1066+Paths begin with a piece of data called a `beak`. A beak is formally a
1067+`(p=ship q=desk r=case)`; it has three components, and might look like
1068+`/~dozbud-namsep/home/11`.
1069+
1070+The first `beak` component is `ship`, which is, as you might guess, the name of
1071+an Urbit ship. The second component is `desk`, which is a workspace meant to
1072+contain other directories; the default desk is `%home`. The third component is
1073+`case`, which represents version information in various ways: date and time;
1074+a version sequence, which is a value incremented by one whenever a file on the
1075+given `desk` is modified; or an arbitrary plaintext label.
1076+
1077+You can find what your `beak` is at any given moment by
1078+typing `%` in the Dojo and looking at the first three results.
1079+
1080+We use `beak`s because, unlike the current internet, the Urbit network uses a
1081+global namespace. That means that a file named `example.hoon` in the `/gen`
1082+directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
1083+universal address to anyone else on the network:
1084+`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
1085+course, doesn't mean that everyone on the network has privileges to access that
1086+path.
1087+
1088+The structure that combines a `beak` with further path information is called a
1089+`beam`.
1090+
1091+#### Relative paths
1092+
1093+The `%` command, which we gestured at in the above section, represents the
1094+**relative path**, which is the path where you are currently working. If your
1095+working directory is just your home desk, indicated by the
1096+prompt `~your-planet:dojo>`, then running the command below will print your
1097+working directory's `beam` information: your `beak`, and a `~` that represents
1098+the empty list since no path is present.
1099+
1100+```
1101+~your-urbit:dojo> %
1102+```
1103+
1104+`%`s can be stacked to indicate one level further up in the hierarchy for each
1105+additional `%`. Try the following command:
1106+
1107+```
1108+~your-planet:dojo> %%%
1109+```
1110+
1111+You'll probably notice that it only has your ship name and the empty list. The
1112+two additional `%`s abandoned the `case` and the `desk` information by moving
1113+up twice the hierarchy.
1114+
1115+There are no local relative paths. `/foo/bar` must be written as
1116+`%/foo/bar`.
1117+
1118+#### Substitution
1119+
1120+You don't need to write out the explicit path every time you want to reference
1121+somewhere outside of your working directory. You can substitute `=` for the
1122+segments of a path.
1123+
1124+Recall that a full address in the the Urbit namespace is a `beam`: the
1125+`/ship/desk/case/path`. If you've switched to another desk before, you're
1126+already familiar with substitution syntax:
1127+
1128+```
1129+~your-urbit:dojo> =dir /=sandbox=
1130+```
1131+
1132+The above command substitutes uses substitution to use your current `ship` and
1133+`case`; only the `desk` argument, which is located between the other two, is
1134+given something new. Without substitution, you would need to write:
1135+
1136+```
1137+~your-urbit:dojo> =dir /~your-urbit/home/85
1138+```
1139+
1140+Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
1141+paths. For example, if you are in the `/gen` directory, you can reference a file
1142+in the `/app` directory like below. (`+cat` displays the contents of a file).
1143+
1144+```
1145+~your-urbit:dojo> =dir %/gen
1146+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
1147+```
1148+
1149+Note what was substituted out, and note that we don't need to separate `=` with
1150+`/`.
1151+
1152+If we changed our working directory to something called `/gen/gmail`, we could
1153+access a file called
1154+
1155+```
1156+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
1157+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
1158+```
1159+
1160+Because both paths share a directory named `/gmail` at the same position in the
1161+address hierarchy – which, if you recall, is just a `list` – the above command
1162+works!
1163+
1164+We can do the same thing between desks. If `%sandbox` has been merged with
1165+`%home`, the following command will produce the same results as the above
1166+command.
1167+
1168+```
1169+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
1170+```
1171+
1172+Most commonly this is used to avoid having to know the current revision
1173+number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
1174+
1175+#### Changing directories
1176+
1177+Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
1178+
1179+For example, the syntax to navigate to `/home/gen/ask` is:
1180+
1181+```
1182+~your-urbit:dojo> =dir /=home=/gen/ask
1183+```
1184+
1185+This command will turn your prompt into something like this:
1186+
1187+```
1188+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
1189+```
1190+
1191+Using `=dir` without anything else uses the null path, which returns you to
1192+your home desk.
1193+
1194+```
1195+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
1196+```
1197+
1198+Your dojo prompt will turn back into `~your-urbit:dojo>`.
1199+
1200+To go up levels in the path hierarchy, recall the relative path expression
1201+`%`. Stacking them represents another level higher in the hierarchy than
1202+the current working directory for each `%` beyond the initial. The command below
1203+brings you one level up:
1204+
1205+```
1206+~your-urbit:dojo> =dir %/gen
1207+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
1208+```
1209+
1210+### Revision-control
1211+
1212+#### Mount
1213+
1214+Syntax: `|mount /clay/path [Unix-name]`
1215+
1216+Mount the `clay-path` at the Unix mount point `Unix-name`.
1217+
1218+**Examples:**
1219+
1220+```
1221+|mount %/gen generators
1222+```
1223+
1224+Mounts `%/gen` to `/generators` inside your pier directory.
1225+
1226+#### Unmount
1227+
1228+```
1229+|unmount [clay-path || Unix-name]
1230+```
1231+
1232+Unmount the path or name from Unix.
1233+
1234+**Examples:**
1235+
1236+```
1237+|unmount %/gen
1238+```
1239+
1240+Unmounts the Clay path `%/gen` from whatever name it was mounted as.
1241+
1242+```
1243+|unmount %generators
1244+```
1245+
1246+Unmounts the Unix path `/generators`.
1247+
1248+#### Merge
1249+
1250+```
1251+|merge desk beak[, =gem strategy]
1252+```
1253+
1254+Merges a `beak` into a `desk` using an optional merge `strategy`.
1255+
1256+A `beak` is a ship-desk-case triple, encoded as a
1257+path(`/~dozbud/home/2`)
1258+
1259+**Examples:**
1260+
1261+```
1262+|merge %home-work /=home=, =gem %fine
1263+```
1264+
1265+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
1266+
1267+```
1268+|merge %examples ~wacbex-ribmex %examples
1269+```
1270+
1271+Merge the `%examples` desk from `~waxbex-ribmex`
1272+
1273+#### Sync
1274+
1275+```
1276+|sync desk plot [plot-desk]
1277+```
1278+
1279+Subscribe to continuous updates from remote `plot` on local `desk`.
1280+`plot-desk` can specify the remote `desk` name. When omitted it defaults
1281+to being the same as `desk`. Non-comet urbits have
1282+`|sync %home ~parent %kids` automatically set up (where `~parent` is the
1283+planet that issued a moon, the star that issued a planet, or the galaxy
1284+that issued a star).
1285+
1286+**Examples:**
1287+
1288+```
1289+|sync %home-local ~dozbud %home
1290+
1291+|sync %home ~doznec
1292+```
1293+
1294+#### Unsync
1295+
1296+```
1297+|unsync desk plot [plot-desk]
1298+```
1299+
1300+Unsubscribe from updates from remote `plot` on local `desk` with
1301+optional `plot-desk`. Arguments must match original `|sync` command.
1302+
1303+Example:
1304+
1305+```
1306+|unsync %home-local ~dozbud %home
1307+```
1308+
1309+#### Label
1310+
1311+```
1312+|label desk name`
1313+```
1314+
1315+Label the current version of `desk` `name`.
1316+
1317+Example:
1318+
1319+```
1320+|label %home release
1321+```
1322+
1323+### Merge strategies
1324+
1325+`%init` - used if it's the first commit to a desk. Also can be used to
1326+"reinitialize" a desk – revision numbers keep going up, but the new
1327+revision isn't necessarily a descendent of the previously numbered
1328+version, allowing merges to be rerun.
1329+
1330+`%this` - keep what's in Bob's desk, but join the ancestry.
1331+
1332+`%that` - take what's in Alice's desk, but join the ancestry. This is
1333+the reverse of `%this`. This is different from `%init` because the new
1334+commit has both sides in its ancestry.
1335+
1336+`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
1337+ancestry of the other.
1338+
1339+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
1340+use as our merge base.
1341+
1342+A `%meet` merge only succeeds if the changes from the merge base to
1343+Alice's head (hereafter, "Alice's changes") are in different files than
1344+Bob's changes. In this case, the parents are both Alice's and Bob's
1345+heads, and the data is the merge base plus Alice's changed files plus
1346+Bob's changed files.
1347+
1348+A `%mate` merge attempts to merge changes to the same file when both
1349+Alice and Bob change it. If the merge is clean, we use it; otherwise, we
1350+fail. A merge between different types of changes – for example,
1351+deleting a file vs changing it – is always a conflict. If we succeed,
1352+the parents are both Alice's and Bob's heads, and the data is the merge
1353+base plus Alice's changed files plus Bob's changed files plus the merged
1354+files.
1355+
1356+A `%meld` merge will succeed even if there are conflicts. If there are
1357+conflicts in a file, then we use the merge base's version of that file,
1358+and we produce a set of files with conflicts. The parents are both
1359+Alice's and Bob's heads, and the data is the merge base plus Alice's
1360+changed files plus Bob's changed files plus the successfully merged
1361+files plus the merge base's version of the conflicting files.
1362+
1363+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
1364+doesn't we use an `%init` merge. Otherwise, we progressively try
1365+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
1366+merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
1367+the scratch desk with the `%meld` option to force the merge. Finally, we
1368+annotate any conflicts, if we know how.
1369+
1370+### Manipulation
1371+
1372+#### `+cat`
1373+
1374+Syntax: `+cat path [path ...]`
1375+
1376+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
1377+contents. If that `path` is a file, the contents of the file is printed. If the
1378+`path` terminates in a directory, the list of names at that path is produced.
1379+
1380+#### `+ls`
1381+
1382+Syntax: `+ls path`
1383+
1384+Similar to Unix `ls`. `+ls` takes a single `path`.
1385+
1386+Produces a list of names at the `path`.
1387+
1388+```
1389+~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
1390+```
1391+
1392+#### `|rm`
1393+
1394+Syntax: `|rm path`
1395+
1396+Remove the data at `path`. `Path` must be a path to the actual node, not a
1397+'directory'.
1398+
1399+#### `|cp`
1400+
1401+Syntax: `|cp to from`
1402+
1403+Copy the file at `from` into the path `to`.
1404+
1405+#### `|mv`
1406+
1407+Syntax: `|mv to from`
1408+
1409+Move the file at `from` into the path `to`.
1410+
1411+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
1412+doesn't happen unless the `|cp` succeeds.