@@ -6,144 +6,38 @@ title: Getting started
66
77# Getting started
88
9−Once urbit is installed, if you have an invitation, it's a planet
10−like `~fintud-macrep` and a ticket like
11−`~fortyv-tombyt-tabsen-sonres`. Run
9+On disk your Urbit is an append-only log and a checkpoint. Or, in simpler terms, a directory where we keep all of your Urbit’s state. We call this a ‘pier’.
1210
13− bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
14−
15−(You can leave the `~` on, but it annoys some Unix shells.)
16−
17−If you don't have an invitation, pick a nickname for your comet,
18−like `mycomet`. Urbit will randomly generate a 128-bit plot:
19−
20− bin/urbit -c mycomet
21−
22−Either way, creating your urbit will take some time. Some of
23−this time involves generating keys; some of it involves
24−downloading code over Urbit itself.
25−
26−If you turn off your pier at any time (either "nicely" with `^D`
27−from talk or the dojo or by power-failure, oom-killer, or other
28−calamity), then you can start it up again with the path to your
29−pier directory (your planet name if you have an invitation,
30−otherwise the name you chose after `-c`):
31−
32− bin/urbit fintud-macrep
33−
34−or
35−
36− bin/urbit mycomet
37−
38−## Basic operation
39−
40−Out 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
43−the prompt.
44−
45−`^D` from either default appliance exits the urbit process.
11+## Initialize
4612
47−If your plot is `~fintud-macrep`, the dojo prompt is
13+When you first start an Urbit we create this pier directory and write to it.
4814
49− ~fintud-macrep:dojo>
15+To start with a planet (`~fintud-macrep`) and ticket (`~fortyv-tombyt-tabsen-sonres`):
5016
51−Type any Hoon expression at the command line and see the result:
52−
53− ~fintud-macrep:dojo> (add 2 2)
54−
55−You'll see:
56−
57− > (add 2 2)
58− 4
59− ~fintud-macrep:dojo>
60−
61−While there are some tools for interacting with urbit's
62−filesystem direclty, often it's useful to edit urbit files from
63−Unix. Use `|mount` to set up a Dropbox-style sync directory in
64−your pier directory:
65−
66− ~fintud-macrep:dojo> |mount %
67− >=
68− ~fintud-macrep:dojo> |unmount %
69− >=
70−
71−Look inside your pier directory to find your files, and edit them
72−with your favorite Unix text editor.
73−
74−Sometimes you want to get files from another urbit. There's two
75−main commands to do this.
76−
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
83−
84−This pulls a bunch of examples from `~wactex-ribmex`'s `%examples`
85−desk and puts them in our `%examples` desk. A desk is a
86−branch (in the git branch sense) of our filesystem. If you want to
87−inspect these files in Unix you'll need to mount the `%examples`
88−desk:
89−
90− ~fintud-macrep:dojo> |mount /=examples= %examples
17+ bin/urbit -w fintud-macrep -t fortyv-tombyt-tabsen-sonres
9118
92−This should result in a `/examples` folder inside your pier.
19+This will create a directory `fintud-macrep/` and begin the initialization process for that planet. Be patient, it can take a few minutes.
9320
94−You can, of course, merge the examples into your `%home`
95−(default) desk if you wish. Merging into a new desk creates it,
96−while merging into an existing desk does an intelligent git-style
97−merge, with conflict resolution and stuff.
21+Without a planet anyone can create a comet:
9822
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
23+ bin/urbit -c comet
10524
106−`|sync` does an initial `|merge`, then listens for changes on the
107−foreign desk and runs `|merge` automatically whenever it changes.
108−By default your `%home` desk is synced to your parent's `%kids`
109−desk, so the entire network is upgraded at once. You may, of
110−course, unsync it, but this voids your warranty.
25+This will create a directory `any-name/` and start up a random 64-bit comet.
11126
112−You can change which desk is your current working directory with:
27+## Orientation
11328
114− ~fintud-macrep:dojo> =dir /=examples=
29+When your Urbit is finished booting you should see a `dojo>` prompt.
11530
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.
31+## Shutdown
11932
120−When you change your desk all commands will use the files from
121−that desk. Unfortunately, changing your working directory to
122−anywhere but the top directory is currently
123−[broken](http://github.com/urbit/urbit/issues/565). If this is
124−fixed when you're reading this, please submit a pull request for
125−this document explaining how to do it!
33+You can turn your Urbit off with `^D` from the `dojo>` prompt.
12634
127−The last command we'll discuss in this quickstart is `+moon`,
128−which only works on planets.
35+## Restart
12936
130− ~fintud-macrep:dojo> +moon
131− "moon: ~ramnec-rossug-fintud-macrep; ticket: ~holtyl-mognyl-dostyp-moslud"
37+To restart your Urbit simply pass the name of your pier:
13238
133−This generates a random moon and ticket. A moon is a subidentity
134−of your planet, so it's a separate urbit that's associated with
135−your planet. If your planet is off, then your moon won't
136−function very well over the network (it'll work just fine
137−locally, of coures).
39+ bin/urbit some-planet
13840
139−You can start up your moon with `bin/urbit -w moon-name -t
140−ticket`. We recommend doing this for development because there
141−are still some instabilities that have the potential to explode
142−your planet if you develop on it. If this happens, then your
143−planet will be unusable until the next continuity breach. If you
144−tell us how you exploded your planet, we may give you a
145−replacement, but it's still a hassle for you.
41+or
14642
147−Don't worry too much about exploding your moons -- you have four
148−billion of them, and they get replenished after every continuity
149−breach. Still do file a bug, though.
43+ bin/urbit comet