content/getting-started/cli.md · urbit.org

git.iko.soy/urbit.org

on 595fcbc help sign in

urbit.org/content/getting-started/cli.md

249 lines 7.9 kB history raw

1+++

2title = "Command line app"

3weight = 2

4description = "Installation instructions for power users."

5+++

7If you're a power user, you can run the Urbit virtual machine directly using the

8command line. This can be run on your local machine or a server in the cloud, we

9just cover the general case here.

11Note there is a much more comprehensive [cloud hosting

12guide](https://operators.urbit.org/manual/running/hosting) which walks through

13setting up Urbit on a [Digital Ocean](https://www.digitalocean.com/) VPS.

15### 1. Install Urbit

17Choose your operating system and run the given command in your terminal to

18download the Urbit runtime:

20{% tabs %}

22{% tab label="MacOS" %}

24```bash

25curl -L https://urbit.org/install/mac/latest | tar xzk --strip=1 && ./urbit

26```

28> Note our Mac build is only compatible with Apple Silicon (M1/M2) via Rosetta.

29> If you have such a machine you may need to run the following command:

30>

31> ```

32> /usr/sbin/softwareupdate --install-rosetta --agree-to-license

33> ```

35{% /tab %}

37{% tab label="Linux" %}

39```shell

40curl -L https://urbit.org/install/linux64/latest | tar xzk --strip=1 && ./urbit

41```

43> Linux users may need to run this command in another terminal window to access

44> your urbit on port 80:

45>

46> ```shell

47> sudo apt-get install libcap2-bin

48> sudo setcap 'cap_net_bind_service=+ep' ./urbit

49> ```

51{% /tab %}

53{% tab label="Linux ARM64" %}

55Note this is for the AArch64 architecture.

57```shell

58curl -L https://urbit.org/install/linux-aarch64/latest | tar xzk --strip=1 && ./urbit

59```

61> Linux users may need to run this command in another terminal window to access

62> your urbit on port 80:

63>

64> ```shell

65> sudo apt-get install libcap2-bin

66> sudo setcap 'cap_net_bind_service=+ep' ./urbit

67> ```

69{% /tab %}

71{% tab label="Windows" %}

73```winbatch

74curl -L https://urbit.org/install/windows/latest | tar -xzkf - --strip-components=1 && urbit

75```

77> Windows 10 build 17063 and later includes the familiar `curl` and `tar`

78> command-line tools. If you're running an older version of Windows, you may need

79> to visit

80> [https://github.com/urbit/urbit/releases/latest](https://github.com/urbit/urbit/releases/latest)

81> in the browser, download the `windows.zip` file, extract it and execute the

82> contained `urbit.exe` file in the command prompt.

84{% /tab %}

86{% /tabs %}

88If successful, you will see a block of output beginning with the line:

90```

91Urbit: a personal server operating function

92```

94### 2. Boot Urbit

96An Urbit instance is intrinsically tied to a unique identity called an **Urbit

97ID**. There are five classes of Urbit ID, but we will consider two here: comets

98and planets.

100- **Comet:** A comet is an identity which anyone can generate themselves, for

101 free. It's a good option to try out Urbit. Comets are limited by the fact they

102 cannot be "factory reset", meaning if your urbit somehow becomes broken or

103 corrupted then you'll have to start again with a new identity. In that sense,

104 they are impermanent.

105

106- **Planet:** A planet is a permanent identity which you own forever. Planets

107 are the class intended for individuals. While there are essentially an

108 unlimited number of comets, planets are more scarce (preventing spamming,

109 among other things). This scarcity means they usually aren't free (though

110 sometimes nice people give them away). This guide will assume you've already

111 acquired a planet. If you haven't, you can refer to the ["Get a planet"

112 guide](https://urbit.org/getting-started/get-planet) before continuing.

113

114Follow the instructions for your case:

115

116{% tabs %}

117

118{% tab label="Boot a Comet" %}

119

120In the terminal, with the `urbit` binary you installed in the previous step, a

121comet can be booted with the `-c` option:

122

123```bash

124./urbit -c mycomet

125```

126

127> `mycomet` will be the name given to the data folder it will create. You can

128> choose any name you like.

129

130It may take a while to initialize the comet (usually only a couple of minutes,

131but it could take longer). When it's done, it'll take you to the dojo prompt

132(the dojo is Urbit's shell):

133

134```

135ames: live on 31337

136http: web interface live on http://localhost:8080

137http: loopback live on http://localhost:12321

138~sampel_marzod:dojo>

139```

140

141You can shut down the comet again by typing `|exit` in the dojo or hitting

142`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

143folder, so you can start it up again by doing:

144

145```bash

146./mycomet/.run

147```

148

149Since comets are often used temporarily and then discarded, kernel updates are

150not enabled by default. If you plan to use your comet for a while, it's a good

151idea to enable updates with the following command in the dojo:

152

153```

154|ota (sein:title our now our)

155```

156

157Lastly, while the dojo is quite powerful, most people use their urbit via

158Landscape, the browser-based UI. In order to access Landscape, you need your web

159login code. You can get this by running the following command in the dojo:

160

161```

162+code

163```

164

165It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`.

166Copy the code it gives you to the clipboard.

167

168{% /tab %}

169

170{% tab label="Boot a Planet" %}

171

172In order to boot a planet, you need a copy of its private keys. If you got your

173planet via a claim link, the passport backup `.zip` file you downloaded will

174contain a file called something like `sampel-palnet-1.key`. If you don't have

175the passport backup or you got your planet by another method, you can instead

176login to [Bridge](https://bridge.urbit.org/), select your planet, go to the OS

177section, and hit the "Download Keyfile" button.

178

179Back in the terminal, with the `urbit` binary you installed in the previous

180step, you can boot your planet with the following command (replacing

181`sampel-palnet` with your own planet and pointing to the location of your

182keyfile):

183

184```bash

185./urbit -w sampel-palnet -k sampel-palnet-1.key

186```

187

188This will create a data folder with the name of your planet and begin booting.

189It may take a while to initialize the planet (usually only a couple of minutes,

190but it could take longer). When it's done, it'll take you to the dojo prompt

191(the dojo is Urbit's shell):

192

193```

194ames: live on 31337

195http: web interface live on http://localhost:8080

196http: loopback live on http://localhost:12321

197~sampel-palnet:dojo>

198```

199

200You can shut down the planet again by typing `|exit` in the dojo or hitting

201`Ctrl+D`. When it's first shut down, the runtime will be copied inside the data

202folder, so you can start it up again by doing:

203

204```bash

205./sampel-palnet/.run

206```

207

208While the dojo is quite powerful, most people use their urbit via Landscape, the

209browser-based UI. In order to access Landscape, you need your web login code.

210You can get this by running the following command in the dojo:

211

212```

213+code

214```

215

216It'll spit out a code that'll look something like `lidlut-tabwed-pillex-ridrup`

217(note this is a separate code to your master ticket). Copy the code it gives you

218to the clipboard.

219

220One last thing: The `sampel-palnet-1.key` keyfile is only needed once, when you

221first boot your planet. Now that it's booted, it's good security practice to

222delete that keyfile.

224{% /tab %}

226{% /tabs %}

228### 3. Login

230While your urbit is running, the web interface called *Landscape* can be

231accessed in the browser. Its URL will usually be either `localhost` or

232`localhost:8080`, depending on your platform. To check the address, you can look

233at the boot messages in the terminal. You should see a line like:

234

235```

236http: web interface live on http://localhost:8080

237```

238

239Whichever address and port it says there is the one to open in the browser.

240

241Once open, you'll be presented with the login screen. Paste in the web login

242code you copied from the dojo in the previous step and hit "continue". You'll

243now be taken to your homescreen, with tiles for the default apps such as Groups

244and Terminal.

245

246### Next steps

247

248Learn how to [get around your

249urbit](https://urbit.org/getting-started/getting-around).