git.iko.soy/urbit.org
on bc0f661 help sign in
urbit.org/docs/user/basic.md
149 lines 5.2 kB history raw
1---
2next: true
3sort: 3
4title: Basic Operation
5---
7# Basic Operation
9Once urbit is installed, if you have an invitation, it's a planet
10like `~fintud-macrep` and a ticket like
11`~fortyv-tombyt-tabsen-sonres`. Run
13 bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
15(You can leave the `~` on, but it annoys some Unix shells.)
17If you don't have an invitation, pick a nickname for your comet,
18like `mycomet`. Urbit will randomly generate a 128-bit plot:
20 bin/urbit -c mycomet
22Either way, creating your urbit will take some time. Some of
23this time involves generating keys; some of it involves
24downloading code over Urbit itself.
26If you turn off your pier at any time (either "nicely" with `^D`
27from talk or the dojo or by power-failure, oom-killer, or other
28calamity), then you can start it up again with the path to your
29pier directory (your planet name if you have an invitation,
30otherwise the name you chose after `-c`):
32 bin/urbit fintud-macrep
34or
36 bin/urbit mycomet
38## Basic operation
40Out of the box, your urbit is running two default appliances,
41`:dojo` (a shell or REPL) and `:talk`. Switch between them with
42`^X`. Note that all apps share an output log, but `^X` switches
43the prompt.
45`^D` from either default appliance exits the urbit process.
47If your plot is `~fintud-macrep`, the dojo prompt is
49 ~fintud-macrep:dojo>
51Type any Hoon expression at the command line and see the result:
53 ~fintud-macrep:dojo> (add 2 2)
55You'll see:
57 > (add 2 2)
58 4
59 ~fintud-macrep:dojo>
61While there are some tools for interacting with urbit's
62filesystem direclty, often it's useful to edit urbit files from
63Unix. Use `|mount` to set up a Dropbox-style sync directory in
64your pier directory:
66 ~fintud-macrep:dojo> |mount %
67 >=
68 ~fintud-macrep:dojo> |unmount %
69 >=
71Look inside your pier directory to find your files, and edit them
72with your favorite Unix text editor.
74Sometimes you want to get files from another urbit. There's two
75main commands to do this.
77 ~fintud-macrep:dojo> |merge %examples ~wactex-ribmex %examples
78 >=
79 ; ~wactex-ribmex is your neighbor
80 ; ~wactex-ribmex is your neighbor
81 [time passes...]
82 merged with strategy %init
84This pulls a bunch of examples from `~wactex-ribmex`'s `%examples`
85desk and puts them in our `%examples` desk. A desk is a
86branch (in the git branch sense) of our filesystem. If you want to
87inspect these files in Unix you'll need to mount the `%examples`
88desk:
90 ~fintud-macrep:dojo> |mount /=examples= %examples
92This should result in a `/examples` folder inside your pier.
94You can, of course, merge the examples into your `%home`
95(default) desk if you wish. Merging into a new desk creates it,
96while merging into an existing desk does an intelligent git-style
97merge, with conflict resolution and stuff.
99 ~fintud-macrep:dojo> |sync %examples ~wactex-ribmex %examples
100 >=
101 activated sync from %examples on ~wactex-ribmex to %examples
102 sync succeeded from %examples on ~wactex-ribmex to %examples
103 ~fintud-macrep:dojo> |unsync %examples ~wactex-ribmex %examples
104 ended autosync from %examples on ~wactex-ribmex to %examples
106`|sync` does an initial `|merge`, then listens for changes on the
107foreign desk and runs `|merge` automatically whenever it changes.
108By default your `%home` desk is synced to your parent's `%kids`
109desk, so the entire network is upgraded at once. You may, of
110course, unsync it, but this voids your warranty.
112You can change which desk is your current working directory with:
114 ~fintud-macrep:dojo> =dir /=examples=
116> `dir` is a special dojo variable, but you can also create your
117> own variables with the same syntax. `=my-var (add 2 3)` allows
118> you to use `my-var` for `5` anywhere later on.
120When you change your desk all commands will use the files from
121that desk. Unfortunately, changing your working directory to
122anywhere but the top directory is currently
123[broken](http://github.com/urbit/urbit/issues/565). If this is
124fixed when you're reading this, please submit a pull request for
125this document explaining how to do it!
127The last command we'll discuss in this quickstart is `+moon`,
128which only works on planets.
130 ~fintud-macrep:dojo> +moon
131 "moon: ~ramnec-rossug-fintud-macrep; ticket: ~holtyl-mognyl-dostyp-moslud"
133This generates a random moon and ticket. A moon is a subidentity
134of your planet, so it's a separate urbit that's associated with
135your planet. If your planet is off, then your moon won't
136function very well over the network (it'll work just fine
137locally, of coures).
139You can start up your moon with `bin/urbit -w moon-name -t
140ticket`. We recommend doing this for development because there
141are still some instabilities that have the potential to explode
142your planet if you develop on it. If this happens, then your
143planet will be unusable until the next continuity breach. If you
144tell us how you exploded your planet, we may give you a
145replacement, but it's still a hassle for you.
147Don't worry too much about exploding your moons -- you have four
148billion of them, and they get replenished after every continuity
149breach. Still do file a bug, though.