git.iko.soy/urbit.org
on cbd52c0 help sign in
urbit.org/docs/user/basic.md
143 lines 5.0 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.
88You can, of course, merge the examples into your `%home`
89(default) desk if you wish. Merging into a new desk creates it,
90while merging into an existing desk does an intelligent git-style
91merge, with conflict resolution and stuff.
93 ~fintud-macrep:dojo> |sync %examples ~wactex-ribmex %examples
94 >=
95 activated sync from %examples on ~wactex-ribmex to %examples
96 sync succeeded from %examples on ~wactex-ribmex to %examples
97 ~fintud-macrep:dojo> |unsync %examples ~wactex-ribmex %examples
98 ended autosync from %examples on ~wactex-ribmex to %examples
100`|sync` does an initial `|merge`, then listens for changes on the
101foreign desk and runs `|merge` automatically whenever it changes.
102By default your `%home` desk is synced to your parent's `%kids`
103desk, so the entire network is upgraded at once. You may, of
104course, unsync it, but this voids your warranty.
106You can change which desk is your current working directory with:
108 ~fintud-macrep:dojo> =dir /=examples=
110> `dir` is a special dojo variable, but you can also create your
111> own variables with the same syntax. `=my-var (add 2 3)` allows
112> you to use `my-var` for `5` anywhere later on.
114When you change your desk all commands will use the files from
115that desk. Unfortunately, changing your working directory to
116anywhere but the top directory is currently
117[broken](http://github.com/urbit/urbit/issues/565). If this is
118fixed when you're reading this, please submit a pull request for
119this document explaining how to do it!
121The last command we'll discuss in this quickstart is `+moon`,
122which only works on planets.
124 ~fintud-macrep:dojo> +moon
125 "moon: ~ramnec-rossug-fintud-macrep; ticket: ~holtyl-mognyl-dostyp-moslud"
127This generates a random moon and ticket. A moon is a subidentity
128of your planet, so it's a separate urbit that's associated with
129your planet. If your planet is off, then your moon won't
130function very well over the network (it'll work just fine
131locally, of coures).
133You can start up your moon with `bin/urbit -w moon-name -t
134ticket`. We recommend doing this for development because there
135are still some instabilities that have the potential to explode
136your planet if you develop on it. If this happens, then your
137planet will be unusable until the next continuity breach. If you
138tell us how you exploded your planet, we may give you a
139replacement, but it's still a hassle for you.
141Don't worry too much about exploding your moons -- you have four
142billion of them, and they get replenished after every continuity
143breach. Still do file a bug, though.