content/using/os/shell.md · urbit.org

git.iko.soy/urbit.org

on 2ddfcbb help sign in

urbit.org/content/using/os/shell.md

413 lines 8.2 kB history raw

1+++

2title = "Shell"

3template = "doc.html"

4weight = 2

5+++

7The Dojo is our shell; it processes system commands and returns output. It's a

8good place to quickly experiment with Urbit. On the surface the Dojo is just a

9Hoon REPL. On the inside, the Dojo is a system for operating on and transforming

10data in Urbit.

12### Quickstart

14You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system

15commands.

17#### Math

19Evaluate a Hoon expression (whitespace matters):

21```

22~your-urbit:dojo> (add 2 2)

23~your-urbit:dojo> %+ add 2 2

24```

26Tall-form Hoon may require multiple lines:

28```

29~your-urbit:dojo> %+ add

30~your-urbit:dojo< 2

31~your-urbit:dojo< 2

32```

34Hoon uses something called [the subject](/docs/hoon/hoon-school/the-subject-and-its-legs).

35The Dojo has its own subject and that's where Hoon's equivalent of variables,

36called faces, are stored.

38Use `=var` to save faces to the Dojo subject.

40```

41~your-urbit:dojo> =foo (add 2 2)

42```

44Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

45face in a `.hoon` file in this way.

47#### System commands

49Use `=dir` to set the current working directory:

51```

52~your-urbit:dojo> =dir %/gen

53```

55(`%` represents your current directory. For a complete explanation on urbit

56paths, see the [filesystem section](#filesystem).)

58Generators (files in `/gen`) are run with `+`:

60```

61~your-urbit:dojo> +hello 'world'

62```

64Save output to a file in `%clay` with `*`:

66```

67~your-urbit:dojo> *some/file/path/hoon 'hello world'

68```

70Run system commands from `:hood`, like `reload`, using `|`:

72```

73~your-urbit:dojo> |reload %eyre

74```

76### Generators

78Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`

79directory. Many Dojo commands exist in the form of generators. The syntax for

80running a generator is `+genname` for a generator saved as `genname.hoon`.

82#### `+cat`

84Accepts a path and displays the file. Similar to Unix `cat`.

86```

87~your-urbit:dojo> +cat %/gen/curl/hoon

88```

90#### `+code`

92Generates a code that is used to remotely log into your ship. No

93arguments.

95```

96~your-urbit:dojo> +code

97```

99You can change your code to a new randomly generated one by entering `|code

100%reset`. Please note that this will prevent [Bridge](/docs/glossary/bridge)

101from being able to derive your code in the future.

102

103#### `+curl`

104

105Retrieves data from a URL. Accepts a `tape`. Similar to Unix `curl`.

106

107```

108~your-urbit:dojo> +curl "http://nyt.com"

109```

110

111#### `+hello`

112

113Just prints the argument. Accepts a `@ta`.

114

115```

116~your-urbit:dojo> +hello 'mars'

117```

118

119#### `+ls`

120

121Similar to Unix `ls`. Accepts a path.

122

123```

124~your-urbit:dojo> +ls %/gen

125~your-urbit:dojo> +ls /~talsur-todres/home/2/gen/program

126```

127

128#### `+solid`

129

130Compile the current state of the kernel and output a

131noun. Usually downloaded to a file in unix. No arguments.

132

133```

134~your-urbit:dojo> .urbit/pill +solid

135```

136

137#### `+test`

138

139Testrunner. Can test multiple generators at once, conventionally ones

140in the `/test` folder. Takes a path.

141

142```

143~your-urbit:dojo> +test /lib

144```

145

146#### `+ticket`

147

148Generate a ticket for an urbit ship. Takes an urbit name (`@p`).

149

150

151```

152~your-urbit:dojo> +ticket ~talsur-todres-your-urbit

153```

154

155#### `+tree`

156

157Generate a recursive directory listing. Takes a path.

158

159```

160~your-urbit:dojo> +tree %/sys

161```

162

163### Hood

164

165The hood is the system daemon. See `gen/hood` and `app/hood`.

166

167`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts

168an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).

169

170```

171~your-urbit:dojo> |hi ~binzod "you there?"

172```

173

174`|link` / `|unlink` - Link / unlink a remote app. Accepts an

175Urbit name and an app name.

176

177```

178~your-urbit:dojo> |link ~talsur-todres %octo

179```

180

181`|mass` - Prints the current memory usage of all the kernel modules.

182No arguments.

183

184```

185~your-urbit:dojo> |mass

186```

187

188`|reload` - Reloads a kernel module (vane) from source. Accepts any

189number of vane names.

190

191```

192~your-urbit:dojo> |reload %clay %eyre

193```

194

195`|reset` - Reloads `hoon.hoon` and all modules. No arguments.

196

197```

198~your-urbit:dojo> |reset

199```

200

201`|start` - Starts an app. Accepts an app name.

202

203```

204~your-urbit:dojo> |start %curl

205```

206

207---

208

209### Dojo manual

210

211#### Sources and sinks

212

213A Dojo command is either a **source** or a **sink**. A source is just something

214that can be printed to your console or the result of some computation. A

215sink is an **effect**: a change to the filesystem, a network message, a

216change to your environment, or a typed message to an app.

217

218Sources can be chained together, but we can only produce one effect per

219command.

220

221#### Sinks

222

223#### `=` - Set variable

224

225Set any environment variable:

226

227```

228~your-urbit:dojo> =foo 42

229~your-urbit:dojo> (add 2 foo)

230

23144

232```

233

234Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a

235variable in a `.hoon` file in this way.

236

237#### Special variables

238

239There are a few special variables that the Dojo maintains.

240

241#### `:` - Send to app

242

243`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.

244

245Send a `helm-hi` message to `hood`:

246

247```

248~your-urbit:dojo> :hood &helm-hi 'hi'

249```

250

251Apps usually expect marked data, so `&` is often used here.

252

253#### `*` - Save in `%clay`

254

255Save a new `.hoon` file in `gen`:

256

257```

258~your-urbit:dojo> *%/gen/foo/hoon '# hello'

259```

260

261The last component of the path is expected to be the mark (or mime

262type).

263

264#### `.` - Export to Unix

265

266Export a noun to Unix with `.`:

267

268```

269~your-urbit:dojo> .foo/bar/baz (add 2 2)

270```

271

272Which creates a file at `pier/.urb/put/foo/bar.baz`.

273

274This is very often used with `+solid`:

275

276```

277~your-urbit:dojo> .urbit/pill +solid

278```

279

280Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`

281

282### Sources

283

284#### `_` - Run a function

285

286Use `_` to run a gate (or function):

287

288Write an arbitrary function and pass data to it:

289

290```

291~your-urbit:dojo> _|=([a=@] (mul a 3)) 3

2929

293```

294

295Use a function to get the status code from an http request:

296

297```

298~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com

299301

300```

301

302#### `+` `-` - HTTP requests

303

304`+http[s]://example.com` - sends a GET request

305

306`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the

307JSON `"hi"` in the body.

308

309`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the

310JSON `"hi"` in the body.

311

312Note that the first of these is a source while the last two are sinks.

313

314#### `+` - Generators

315

316Generators are simple Hoon scripts loaded from the filesystem. They live

317in `gen/`.

318

319An example of a generator that is built into your urbit is `+code`. It produces

320the code needed to log into your ship remotely.

321

322```

323~your-urbit:dojo> +code

324fintyr-haldet-fassev-solhex

325```

326

327### Variables

328

329You can use `=` to set an environment variable in Dojo, but there are

330a few reserved names that have special uses.

331

332#### `dir`

333

334Current working `%clay` desk and revision. Read / write.

335

336**Examples:**

337

338```

339~your-urbit:dojo> =dir %/gen

340~your-urbit:dojo> +ls %

341404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/

342```

343

344#### `lib`

345

346Current set of libraries (`/lib`) in your environment. Can be set

347with `/+`. Read / write.

348

349**Examples:**

350

351```

352~your-urbit:dojo> /+ number-to-words

353```

354Now we can use arms from lib/number-to-words.hoon

355```

356~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)

357```

358

359#### `sur`

360

361Current set of structures (`/sur`) in your environment. Can be set

362with `/-`. Read / write.

363

364**Examples:**

365

366```

367~your-urbit:dojo> /- sole

368```

369Now we can use arms in sur/sole.hoon.

370```

371~your-urbit:dojo> `sole-effect:sole`[%bel ~]

372```

373

374#### `now`

375

376The current (128-bit `@da`) time. Read-only.

377

378**Example:**

379

380```

381~your-urbit:dojo> now

382~2016.3.21..21.10.57..429a

383```

384

385#### `our`

386

387The current urbit ship. Read-only.

388

389**Example:**

390

391```

392~your-urbit:dojo> our

393~your-urbit

394```

395

396#### `eny`

397

398512 bits of entropy. Read-only.

399

400**Example:**

401

402```

403~your-urbit:dojo> eny

404\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/

405 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn

406\/

407```

408

409### Troubleshooting

410

411If you encounter `%dy-edit-busy` while entering commands, it is

412because your Dojo is blocked on a timer or an HTTP request. Type backspace

413and your Dojo will end the blocked command.