@@ -263,65 +263,6 @@ Configuring a ship's domain causes the `:acme` app to request an HTTPS certifica
263263
264264The 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).
265265
266−## Messaging {#messaging}
267−
268−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.
269−
270−### Quickstart
271−
272−The most common use for `:chat-cli` right now is, of course, communicating in group chats.
273−
274−### Joining a chat
275−
276−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.
277−
278−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.
279−
280−Then:
281−
282−```
283−~sampel-palnet:chat-cli/ ;join ~darrux-landes/general
284−```
285−
286−Now that you're in, try post a line to `~darrux-landes/general`:
287−
288−```
289−~sampel-palnet:chat-cli= Hello, world!
290−```
291−
292−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:
293−
294−```
295−~sampel-palnet:chat-cli= ;chats
296−~darrux-landes/general
297−```
298−
299−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.
300−
301−```
302−~sampel-palnet:chat-cli= ;+
303−~sampel-palnet:chat-cli+
304−```
305−
306−Use `;leave` to unsubscribe from a channel:
307−
308−```
309−~sampel-palnet:chat-cli= ;leave ~darrux-landes/general
310−```
311−
312−Now, let's create a channel we can invite some friends to:
313−
314−```
315−~sampel-palnet:chat-cli= ;create channel /my-channel
316−```
317−
318−Now you can tell your friends to `;join ~your-urbit/my-channel`.
319−
320−In order to see messages in `:chat-cli` you may need to do the following in Dojo:
321−
322−```
323−:chat-cli %connect
324−```
325266
326267### Hoon
327268
@@ -384,1027 +325,3 @@ Detailed message output will look something like this:
384325let's try selecting this message!
385326```
386327
387−### Creating and managing chats {#chat-management}
388−
389−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.
390−
391−#### Create
392−
393−Syntax: `;create [type] /name +`, where `+` represents an optional glyph.
394−
395−Creates and joins a chat, where `[type]` is any of the following:
396−- `channel`: public chat. Has a blacklist for write control.
397−- `village`: invite-only chat.
398−- `journal`: publicly readable, invite-only for writing.
399−- `mailbox`: publicly writeable, invite-only for reading.
400−
401−Let's create an example mailbox:
402−
403−```
404−~sampel-palnet:chat-cli> ;create mailbox /coolbox ^
405−```
406−
407−#### Delete
408−
409−Syntax: `;delete /name`
410−
411−Deletes a chat.
412−
413−#### Permission management
414−
415−You can permit and ban people from reading and/or writing to the chats you host, using `;invite` and `;banish` command respectively.
416−
417−Syntax: `;invite [rw] /name ~ships`
418−
419−Where `rw` is either `r`, `w`, or `rw`, representing "read" and "write" permissions.
420−And where `~ships` is a comma-seperated list of ships to invite.
421−
422−For example, to grant two people full access to a `village` we created:
423−
424−```
425−~sampel-palnet:chat-cli> ;invite rw /hidden-village ~ravmel-ropdyl, ~rapfyr-diglyt
426−```
427−
428−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:
429−
430−```
431−~sampel-palnet:chat-cli> ;banish w /hidden-village ~rapfyr-diglyt
432−```
433−
434−#### Chat glyphs
435−
436−Glyphs are found at the end of your prompt, as a quick indicator of where
437−your messages will be sent.
438−
439−Glyphs are assigned by chat hash out of the following list:
440−
441−```
442−! @ # $ % ^ & ( ) - = _ + [ ] { } ; ' \ : " , . < > ?
443−```
444−
445−Alphanumeric characters and `|#/*~` are reserved; all others can be manually assigned.
446−
447−For example, `-` the glyph at the end of the prompt below might indicates that
448−messages sent from this prompt will go to some chat with that glyph:
449−
450−```
451−~sampel-palnet:chat-cli-
452−```
453−
454−To see what chat is bound to a glyph, use the `;what` command followed by the
455−glyph in question, or use `;what` without specifying a glyph to see all of your
456−subscriptions which are bound to glyphs. For example, to see `=`:
457−
458−```
459−~sampel-palnet:chat-cli> ;what =
460−~dopzod/urbit-help
461−```
462−
463−To see all of your glyph bindings:
464−
465−```
466−~sampel-palnet:chat-cli> ;what
467−> ~paldev/numismatic-forum
468−. ~middev/ny-martians
469−= ~dopzod/urbit-help
470−```
471−
472−When the messaging target doesn't have a glyph, we see their name at the end of
473−the prompt instead. Here we're talking into `~dannum-mitryl/homework`:
474−
475−```
476−~sampel-palnet:chat-cli[~dannum-mitryl/homework]
477−```
478−
479−#### Bind
480−
481−Syntax: `;bind [glyph] ~host/chat-name`
482−
483−Assigns the chosen glyph to a chat.
484−
485−For example:
486−
487−```
488−~sampel-palnet:chat-cli> ;bind + ~dopzod/urbit-help
489−```
490−
491−#### Unbind
492−
493−Syntax: `;unbind [glyph] ~host/chat-name`
494−
495−Unassigns the chosen glyph from a chat owned by your ship.
496−
497−For example:
498−
499−```
500−~sampel-palnet:chat-cli> ;unbind + ~dopzod/urbit-help
501−```
502−
503−If you don't specify a chat, all bindings for that glyph are removed.
504−
505−#### Prefixes
506−
507−Received posts are prefixed with a glyph to let you know what the
508−audience is. You can activate an individual post to see the full
509−audience.
510−
511−There are a few special-purpose "glyphs":
512−
513−- `|` - Informational messages
514−- `*` - Posts to a target you don't have a glyph binding for
515−
516−
517−### Configuration
518−
519−#### Set audience
520−
521−`;~ship/chat`
522−
523−Set audience to `~ship/chat`.
524−
525−#### Set audience by glyph
526−
527−Syntax: `;[glyph]`
528−
529−Set audience to the chat previously bound to the chosen glyph.
530−
531−#### Set audience to own chat
532−
533−Syntax: `;/chat`
534−
535−Set audience to a chat on your own ship.
536−
537−### Miscellaneous configuration
538−
539−#### Change timezone
540−
541−Syntax: `;set timezone [+/-][hours]`
542−
543−Adjust the display of timestamps to a specific timezone. Relative to UTC.
544−
545−#### Set width
546−
547−Syntax: `;set width [number]`
548−
549−Set the rendering width of `:chat-cli` to a specific number of characters.
550−(Minimum of 30.)
551−
552−#### Show timestamps
553−
554−Syntax: `;set showtime`
555−
556−Show the timestamp for each message. This is set by default.
557−
558−#### Hide timestamps
559−
560−Syntax: `;unset showtime`
561−
562−Stop showing the timestamp for each message.
563−
564−#### Sound notification on
565−
566−Syntax: `;set notify`
567−
568−Emit a terminal bell sound if your six-syllable ship name is mentioned in
569−a message. This is set by default.
570−
571−#### Sound notification off
572−
573−Syntax `;unset notify`
574−
575−Do not notify when your ship name is mentioned.
576−
577−
578−## S3 {#s3}
579−
580−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).
581−
582−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).
583−
584−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.
585−
586−### Bucket Setup
587−
588−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.
589−
590−### Add your credentials: Landscape
591−
592−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!
593−
594−### Add your credentials: Dojo
595−
596−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.
597−
598−```
599−:s3-store|set-endpoint 'endpoint.mys3provider.com'
600−:: AWS endpoint example: s3-us-west-2.amazonaws.com
601−:: Digital Ocean endpoint example: sfo2.digitaloceanspaces.com
602−:s3-store|set-access-key-id 'MYACCESSKEYID'
603−:s3-store|set-secret-access-key 'MYSECRETACCESSKEY'
604−:s3-store|set-current-bucket 'yourbucketname'
605−```
606−
607−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.
608−
609−## Shell {#using-the-shell}
610−
611−The Dojo is our shell; it processes system commands and returns output. It's a
612−good place to quickly experiment with Urbit. On the surface the Dojo is just a
613−Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
614−data in Urbit.
615−
616−### Quickstart
617−
618−You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
619−commands.
620−
621−#### Math
622−
623−Evaluate a Hoon expression (whitespace matters):
624−
625−```
626−~your-urbit:dojo> (add 2 2)
627−~your-urbit:dojo> %+ add 2 2
628−```
629−
630−Tall-form Hoon may require multiple lines:
631−
632−```
633−~your-urbit:dojo> %+ add
634−~your-urbit:dojo< 2
635−~your-urbit:dojo< 2
636−```
637−
638−Hoon uses something called [the subject](@/docs/tutorials/hoon/hoon-school/the-subject-and-its-legs.md).
639−The Dojo has its own subject and that's where Hoon's equivalent of variables,
640−called faces, are stored.
641−
642−Use `=var` to save faces to the Dojo subject.
643−
644−```
645−~your-urbit:dojo> =foo (add 2 2)
646−```
647−
648−Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
649−face in a `.hoon` file in this way.
650−
651−#### System commands
652−
653−Use `=dir` to set the current working directory:
654−
655−```
656−~your-urbit:dojo> =dir %/gen
657−```
658−
659−(`%` represents your current directory. For a complete explanation on urbit
660−paths, see the [filesystem section](#filesystem).)
661−
662−Generators (files in `/gen`) are run with `+`:
663−
664−```
665−~your-urbit:dojo> +hello 'world'
666−```
667−
668−Save output to a file in `%clay` with `*`:
669−
670−```
671−~your-urbit:dojo> *some/file/path/hoon 'hello world'
672−```
673−
674−Run system commands from `:hood`, like `reload`, using `|`:
675−
676−```
677−~your-urbit:dojo> |reload %eyre
678−```
679−
680−### Generators
681−
682−Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
683−directory. Many Dojo commands exist in the form of generators. The syntax for
684−running a generator is `+genname` for a generator saved as `genname.hoon`.
685−
686−#### `+cat`
687−
688−Accepts a path and displays the file. Similar to Unix `cat`.
689−
690−```
691−~your-urbit:dojo> +cat %/gen/curl/hoon
692−```
693−
694−#### `+code`
695−
696−Generates a code that is used to remotely log into your ship. No
697−arguments.
698−
699−```
700−~your-urbit:dojo> +code
701−```
702−
703−You can change your code to a new randomly generated one by entering `|code
704−%reset`. Please note that this will prevent [Bridge](@/docs/glossary/bridge.md)
705−from being able to derive your code in the future.
706−
707−#### `+curl`
708−
709−Retrieves data from a URL. Accepts a `tape`. Similar to Unix `curl`.
710−
711−```
712−~your-urbit:dojo> +curl "http://nyt.com"
713−```
714−
715−#### `+hello`
716−
717−Just prints the argument. Accepts a `@ta`.
718−
719−```
720−~your-urbit:dojo> +hello 'mars'
721−```
722−
723−#### `+ls`
724−
725−Similar to Unix `ls`. Accepts a path.
726−
727−```
728−~your-urbit:dojo> +ls %/gen
729−~your-urbit:dojo> +ls /~talsur-todres/home/2/gen/program
730−```
731−
732−#### `+solid`
733−
734−Compile the current state of the kernel and output a
735−noun. Usually downloaded to a file in unix. No arguments.
736−
737−```
738−~your-urbit:dojo> .urbit/pill +solid
739−```
740−
741−#### `+test`
742−
743−Testrunner. Can test multiple generators at once, conventionally ones
744−in the `/test` folder. Takes a path.
745−
746−```
747−~your-urbit:dojo> +test /lib
748−```
749−
750−#### `+ticket`
751−
752−Generate a ticket for an urbit ship. Takes an urbit name (`@p`).
753−
754−
755−```
756−~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
757−```
758−
759−#### `+tree`
760−
761−Generate a recursive directory listing. Takes a path.
762−
763−```
764−~your-urbit:dojo> +tree %/sys
765−```
766−
767−### Hood
768−
769−The hood is the system daemon. See `gen/hood` and `app/hood`.
770−
771−`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
772−an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
773−
774−```
775−~your-urbit:dojo> |hi ~binzod "you there?"
776−```
777−
778−`|link` / `|unlink` - Link / unlink a remote app. Accepts an
779−Urbit name and an app name.
780−
781−```
782−~your-urbit:dojo> |link ~talsur-todres %octo
783−```
784−
785−`|mass` - Prints the current memory usage of all the kernel modules.
786−No arguments.
787−
788−```
789−~your-urbit:dojo> |mass
790−```
791−
792−`|reload` - Reloads a kernel module (vane) from source. Accepts any
793−number of vane names.
794−
795−```
796−~your-urbit:dojo> |reload %clay %eyre
797−```
798−
799−`|reset` - Reloads `hoon.hoon` and all modules. No arguments.
800−
801−```
802−~your-urbit:dojo> |reset
803−```
804−
805−`|start` - Starts an app. Accepts an app name.
806−
807−```
808−~your-urbit:dojo> |start %curl
809−```
810−
811−---
812−
813−### Dojo manual
814−
815−#### Sources and sinks
816−
817−A Dojo command is either a **source** or a **sink**. A source is just something
818−that can be printed to your console or the result of some computation. A
819−sink is an **effect**: a change to the filesystem, a network message, a
820−change to your environment, or a typed message to an app.
821−
822−Sources can be chained together, but we can only produce one effect per
823−command.
824−
825−#### Sinks
826−
827−#### `=` - Set variable
828−
829−Set any environment variable:
830−
831−```
832−~your-urbit:dojo> =foo 42
833−~your-urbit:dojo> (add 2 foo)
834−
835−44
836−```
837−
838−Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
839−variable in a `.hoon` file in this way.
840−
841−#### Special variables
842−
843−There are a few special variables that the Dojo maintains.
844−
845−#### `:` - Send to app
846−
847−`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
848−
849−Send a `helm-hi` message to `hood`:
850−
851−```
852−~your-urbit:dojo> :hood &helm-hi 'hi'
853−```
854−
855−Apps usually expect marked data, so `&` is often used here.
856−
857−#### `*` - Save in `%clay`
858−
859−Save a new `.hoon` file in `gen`:
860−
861−```
862−~your-urbit:dojo> *%/gen/foo/hoon '# hello'
863−```
864−
865−The last component of the path is expected to be the mark (or mime
866−type).
867−
868−#### `.` - Export to Unix
869−
870−Export a noun to Unix with `.`:
871−
872−```
873−~your-urbit:dojo> .foo/bar/baz (add 2 2)
874−```
875−
876−Which creates a file at `pier/.urb/put/foo/bar.baz`.
877−
878−This is very often used with `+solid`:
879−
880−```
881−~your-urbit:dojo> .urbit/pill +solid
882−```
883−
884−Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
885−
886−### Sources
887−
888−#### `_` - Run a function
889−
890−Use `_` to run a gate (or function):
891−
892−Write an arbitrary function and pass data to it:
893−
894−```
895−~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
896−9
897−```
898−
899−Use a function to get the status code from an http request:
900−
901−```
902−~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
903−301
904−```
905−
906−#### `+` `-` - HTTP requests
907−
908−`+http[s]://example.com` - sends a GET request
909−
910−`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
911−JSON `"hi"` in the body.
912−
913−`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
914−JSON `"hi"` in the body.
915−
916−Note that the first of these is a source while the last two are sinks.
917−
918−#### `+` - Generators
919−
920−Generators are simple Hoon scripts loaded from the filesystem. They live
921−in `gen/`.
922−
923−An example of a generator that is built into your urbit is `+code`. It produces
924−the code needed to log into your ship remotely.
925−
926−```
927−~your-urbit:dojo> +code
928−fintyr-haldet-fassev-solhex
929−```
930−
931−### Variables
932−
933−You can use `=` to set an environment variable in Dojo, but there are
934−a few reserved names that have special uses.
935−
936−#### `dir`
937−
938−Current working `%clay` desk and revision. Read / write.
939−
940−**Examples:**
941−
942−```
943−~your-urbit:dojo> =dir %/gen
944−~your-urbit:dojo> +ls %
945−404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
946−```
947−
948−#### `lib`
949−
950−Current set of libraries (`/lib`) in your environment. Can be set
951−with `/+`. Read / write.
952−
953−**Examples:**
954−
955−```
956−~your-urbit:dojo> /+ number-to-words
957−```
958−Now we can use arms from lib/number-to-words.hoon
959−```
960−~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)
961−```
962−
963−#### `sur`
964−
965−Current set of structures (`/sur`) in your environment. Can be set
966−with `/-`. Read / write.
967−
968−**Examples:**
969−
970−```
971−~your-urbit:dojo> /- sole
972−```
973−Now we can use arms in sur/sole.hoon.
974−```
975−~your-urbit:dojo> `sole-effect:sole`[%bel ~]
976−```
977−
978−#### `now`
979−
980−The current (128-bit `@da`) time. Read-only.
981−
982−**Example:**
983−
984−```
985−~your-urbit:dojo> now
986−~2016.3.21..21.10.57..429a
987−```
988−
989−#### `our`
990−
991−The current urbit ship. Read-only.
992−
993−**Example:**
994−
995−```
996−~your-urbit:dojo> our
997−~your-urbit
998−```
999−
1000−#### `eny`
1001−
1002−512 bits of entropy. Read-only.
1003−
1004−**Example:**
1005−
1006−```
1007−~your-urbit:dojo> eny
1008−\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
1009− 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
1010−\/
1011−```
1012−
1013−### Troubleshooting
1014−
1015−If you encounter `%dy-edit-busy` while entering commands, it is
1016−because your Dojo is blocked on a timer or an HTTP request. Type backspace
1017−and your Dojo will end the blocked command.
1018−
1019−
1020−## Filesystem {#filesystem}
1021−
1022−Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
1023−referentially transparent namespace. An easy way to think about it is like typed
1024−`git`.
1025−
1026−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.
1027−
1028−### Quickstart
1029−
1030−This quick-start guide will walk you through some common commands. Follow along
1031−using your Dojo. When you get a `>=` message after entering a command, this means
1032−that the command was successful.
1033−
1034−It's important to note that whenever you want to sync changes from your Unix
1035−directory to your ship, you must use the `|commit %desk` command, where `%desk`
1036−is the desk that you'd like to sync to.
1037−
1038−When developing it's a good idea to use a separate desk. Create a `%sandbox`
1039−desk based on the `%home` desk:
1040−
1041−```
1042−~your-urbit:dojo> |merge %sandbox ~your-urbit %home
1043−```
1044−
1045−Running `our` produces your ship-name, meaning that you can run the following
1046−command instead of typing out the entire thing. Useful for comets due to their
1047−very long names.
1048−
1049−```
1050−~your-urbit:dojo> |merge %sandbox our %home
1051−```
1052−
1053−Most of the time we want to use Clay from Unix. Mount the entire contents of
1054−your `sandbox` desk to Unix:
1055−
1056−```
1057−~your-urbit:dojo> |mount /=sandbox=
1058−```
1059−
1060−To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
1061−displays files in the current directory, and `+cat` displays the contents of
1062−a file.
1063−
1064−We can use `%` to mean "current directory." The result of the command below
1065−is just like using `ls` in a Unix terminal.
1066−
1067−```
1068−~your-urbit:dojo> +ls %
1069−```
1070−
1071−Notice how `+cat %` does the same thing. That's because everything in Clay,
1072−including directories, is a file.
1073−
1074−Sync from your friend `~some-ship`'s `%experiment` desk to your
1075−`%sandbox` desk:
1076−
1077−```
1078−~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
1079−```
1080−
1081−If and when your sync is successful, you will receive a message:
1082−
1083−```
1084−activated sync from %experiment on ~some-ship to %sandbox
1085−```
1086−
1087−The ship that you sync from will get their own message indicating that you're
1088−both connected as peers:
1089−
1090−```
1091−; ~your-urbit is your neighbor.
1092−```
1093−
1094−---
1095−
1096−### Clay manual
1097−
1098−#### Paths
1099−
1100−A path in Clay is a list of URL-safe text, restricted to the characters
1101−`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
1102−meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
1103−In other words, paths are expressed as `/foo/bar/baz`. File extensions are
1104−separated from file names with `/`, not `.`. Extensions are syntactically
1105−identical to subdirectories, except that they must terminate the path.
1106−
1107−Paths begin with a piece of data called a `beak`. A beak is formally a
1108−`(p=ship q=desk r=case)`; it has three components, and might look like
1109−`/~dozbud-namsep/home/11`.
1110−
1111−The first `beak` component is `ship`, which is, as you might guess, the name of
1112−an Urbit ship. The second component is `desk`, which is a workspace meant to
1113−contain other directories; the default desk is `%home`. The third component is
1114−`case`, which represents version information in various ways: date and time;
1115−a version sequence, which is a value incremented by one whenever a file on the
1116−given `desk` is modified; or an arbitrary plaintext label.
1117−
1118−You can find what your `beak` is at any given moment by
1119−typing `%` in the Dojo and looking at the first three results.
1120−
1121−We use `beak`s because, unlike the current internet, the Urbit network uses a
1122−global namespace. That means that a file named `example.hoon` in the `/gen`
1123−directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
1124−universal address to anyone else on the network:
1125−`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
1126−course, doesn't mean that everyone on the network has privileges to access that
1127−path.
1128−
1129−The structure that combines a `beak` with further path information is called a
1130−`beam`.
1131−
1132−#### Relative paths
1133−
1134−The `%` command, which we gestured at in the above section, represents the
1135−**relative path**, which is the path where you are currently working. If your
1136−working directory is just your home desk, indicated by the
1137−prompt `~your-planet:dojo>`, then running the command below will print your
1138−working directory's `beam` information: your `beak`, and a `~` that represents
1139−the empty list since no path is present.
1140−
1141−```
1142−~your-urbit:dojo> %
1143−```
1144−
1145−`%`s can be stacked to indicate one level further up in the hierarchy for each
1146−additional `%`. Try the following command:
1147−
1148−```
1149−~your-planet:dojo> %%%
1150−```
1151−
1152−You'll probably notice that it only has your ship name and the empty list. The
1153−two additional `%`s abandoned the `case` and the `desk` information by moving
1154−up twice the hierarchy.
1155−
1156−There are no local relative paths. `/foo/bar` must be written as
1157−`%/foo/bar`.
1158−
1159−#### Substitution
1160−
1161−You don't need to write out the explicit path every time you want to reference
1162−somewhere outside of your working directory. You can substitute `=` for the
1163−segments of a path.
1164−
1165−Recall that a full address in the the Urbit namespace is a `beam`: the
1166−`/ship/desk/case/path`. If you've switched to another desk before, you're
1167−already familiar with substitution syntax:
1168−
1169−```
1170−~your-urbit:dojo> =dir /=sandbox=
1171−```
1172−
1173−The above command uses substitution to use your current `ship` and
1174−`case`; only the `desk` argument, which is located between the other two, is
1175−given something new. Without substitution, you would need to write:
1176−
1177−```
1178−~your-urbit:dojo> =dir /~your-urbit/sandbox/85
1179−```
1180−
1181−Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
1182−paths. For example, if you are in the `/gen` directory, you can reference a file
1183−in the `/app` directory like below. (`+cat` displays the contents of a file).
1184−
1185−```
1186−~your-urbit:dojo> =dir %/gen
1187−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
1188−```
1189−
1190−Note what was substituted out, and note that we don't need to separate `=` with
1191−`/`.
1192−
1193−If we changed our working directory to something called `/gen/gmail`, we could
1194−access a file called
1195−
1196−```
1197−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
1198−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
1199−```
1200−
1201−Because both paths share a directory named `/gmail` at the same position in the
1202−address hierarchy – which, if you recall, is just a `list` – the above command
1203−works!
1204−
1205−We can do the same thing between desks. If `%sandbox` has been merged with
1206−`%home`, the following command will produce the same results as the above
1207−command.
1208−
1209−```
1210−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
1211−```
1212−
1213−Most commonly this is used to avoid having to know the current revision
1214−number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
1215−
1216−#### Changing directories
1217−
1218−Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
1219−
1220−For example, the syntax to navigate to `/home/gen/ask` is:
1221−
1222−```
1223−~your-urbit:dojo> =dir /=home=/gen/ask
1224−```
1225−
1226−This command will turn your prompt into something like this:
1227−
1228−```
1229−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
1230−```
1231−
1232−Using `=dir` without anything else uses the null path, which returns you to
1233−your home desk.
1234−
1235−```
1236−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
1237−```
1238−
1239−Your dojo prompt will turn back into `~your-urbit:dojo>`.
1240−
1241−To go up levels in the path hierarchy, recall the relative path expression
1242−`%`. Stacking them represents another level higher in the hierarchy than
1243−the current working directory for each `%` beyond the initial. The command below
1244−brings you one level up:
1245−
1246−```
1247−~your-urbit:dojo> =dir %/gen
1248−~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
1249−```
1250−
1251−### Revision-control
1252−
1253−#### Mount
1254−
1255−Syntax: `|mount /clay/path [Unix-name]`
1256−
1257−Mount the `clay-path` at the Unix mount point `Unix-name`.
1258−
1259−**Examples:**
1260−
1261−```
1262−|mount %/gen generators
1263−```
1264−
1265−Mounts `%/gen` to `/generators` inside your pier directory.
1266−
1267−#### Unmount
1268−
1269−```
1270−|unmount [clay-path || Unix-name]
1271−```
1272−
1273−Unmount the path or name from Unix.
1274−
1275−**Examples:**
1276−
1277−```
1278−|unmount %/gen
1279−```
1280−
1281−Unmounts the Clay path `%/gen` from whatever name it was mounted as.
1282−
1283−```
1284−|unmount %generators
1285−```
1286−
1287−Unmounts the Unix path `/generators`.
1288−
1289−#### Merge
1290−
1291−```
1292−|merge desk beak[, =gem strategy]
1293−```
1294−
1295−Merges a `beak` into a `desk` using an optional merge `strategy`.
1296−
1297−A `beak` is a ship-desk-case triple, encoded as a
1298−path(`/~dozbud/home/2`)
1299−
1300−**Examples:**
1301−
1302−```
1303−|merge %home-work /=home=, =gem %fine
1304−```
1305−
1306−Merge `/=home=` into `%home-work` using merge strategy `%fine`.
1307−
1308−```
1309−|merge %examples ~wacbex-ribmex %examples
1310−```
1311−
1312−Merge the `%examples` desk from `~waxbex-ribmex`
1313−
1314−#### Sync
1315−
1316−```
1317−|sync desk plot [plot-desk]
1318−```
1319−
1320−Subscribe to continuous updates from remote `plot` on local `desk`.
1321−`plot-desk` can specify the remote `desk` name. When omitted it defaults
1322−to being the same as `desk`. Non-comet urbits have
1323−`|sync %home ~parent %kids` automatically set up (where `~parent` is the
1324−planet that issued a moon, the star that issued a planet, or the galaxy
1325−that issued a star).
1326−
1327−**Examples:**
1328−
1329−```
1330−|sync %home-local ~dozbud %home
1331−
1332−|sync %home ~doznec
1333−```
1334−
1335−#### Unsync
1336−
1337−```
1338−|unsync desk plot [plot-desk]
1339−```
1340−
1341−Unsubscribe from updates from remote `plot` on local `desk` with
1342−optional `plot-desk`. Arguments must match original `|sync` command.
1343−
1344−Example:
1345−
1346−```
1347−|unsync %home-local ~dozbud %home
1348−```
1349−
1350−#### Label
1351−
1352−```
1353−|label desk name
1354−```
1355−
1356−Label the current version of `desk` `name`.
1357−
1358−Example:
1359−
1360−```
1361−|label %home release
1362−```
1363−
1364−### Merge strategies
1365−
1366−See [Clay merge strategies](@/docs/tutorials/arvo/clay.md#merge-strategies).
1367−
1368−### Manipulation
1369−
1370−#### `+cat`
1371−
1372−Syntax: `+cat path [path ...]`
1373−
1374−Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
1375−contents. If that `path` is a file, the contents of the file is printed. If the
1376−`path` terminates in a directory, the list of names at that path is produced.
1377−
1378−#### `+ls`
1379−
1380−Syntax: `+ls path`
1381−
1382−Similar to Unix `ls`. `+ls` takes a single `path`.
1383−
1384−Produces a list of names at the `path`.
1385−
1386−```
1387−~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
1388−```
1389−
1390−#### `|rm`
1391−
1392−Syntax: `|rm path`
1393−
1394−Remove the data at `path`. `Path` must be a path to the actual node, not a
1395−'directory'.
1396−
1397−#### `|cp`
1398−
1399−Syntax: `|cp to from`
1400−
1401−Copy the file at `from` into the path `to`.
1402−
1403−#### `|mv`
1404−
1405−Syntax: `|mv to from`
1406−
1407−Move the file at `from` into the path `to`.
1408−
1409−In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
1410−doesn't happen unless the `|cp` succeeds.