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