using/shell.md · urbit.org · git.iko.soy

git.iko.soy/urbit.org

on c4ed4fc help sign in

urbit.org/using/shell.md

440 lines 9.0 kB history raw

1+++

2title = "Shell"

3weight = 4

4template = "doc.html"

5+++

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

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

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

9data 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/learn/hoon/hoon-tutorial/the-subject-and-its-legs.md).

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 %/web

53```

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

56paths, see the [filesystem section](@/docs/using/filesystem.md))

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```

99### +curl

101Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.

103```

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

105```

107### +hello

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

111```

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

113```

115### +ls

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

119```

120~your-urbit:dojo> +ls %/web

121~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes

122```

124### +moon

126Generates a random moon from a planet. No arguments.

128```

129~your-urbit:dojo> +moon

130```

132### +solid

134Compile the current state of the kernel and output a

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

137```

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

139```

141### +test

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

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

146```

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

148```

150### +ticket

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

155```

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

157```

159### +tree

161Generate a recursive directory listing. Takes a path.

163```

164~your-urbit:dojo> +tree %/web

165```

167## Hood

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

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

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

174```

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

176```

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

179Urbit name and an app name.

181```

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

183```

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

186No arguments.

188```

189~your-urbit:dojo> |mass

190```

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

193number of vane names.

195```

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

197```

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

201```

202~your-urbit:dojo> |reset

203```

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

207```

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

209```

211---

213## Manual

215## Sources and sinks

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

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

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

220change to your environment, or typed message to an app.

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

223command.

225### Sinks

227#### `=` - Set variable

229Set any environment variable:

231```

232~your-urbit:dojo> =foo 42

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

236```

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

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

241#### Special Variables

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

245#### `:` - Send to app

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

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

251```

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

253```

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

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

259Save a new `.udon` ([Udon](@/docs/using/sail-and-udon.md)) file in `web`:

261```

262~your-urbit:dojo> *%/web/foo/udon '# hello'

263```

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

266type).

268#### `.` - Export to Unix

270Export a noun to Unix with `.`:

272```

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

274```

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

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

280```

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

282```

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

286### Sources

288#### `&` - Mark conversion

290Convert between marks using `&`, with the destination mark first. You can stack multiple mark conversions together, and some marks can only be converted to specific other marks. In this example, [Udon](@/docs/using/sail-and-udon.md#udon) is converted to `&hymn` (a mark which supplies the `html`, `head`, `body` and closing tags) first, before being converted to HTML:

292```

293~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'

294'<html><head></head><body><h1 id="hello">hello</h1></body></html>'

295```

297Performing a conversion straight from Udon to the `&hymn` mark reveals a bit more about its mark conversion:

299```

300~your-urbit:dojo>&hymn &udon ';h1#hello: hello'

301[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]

302```

304As does converting straight from Udon to HTML:

306```

307~your-urbit:dojo>&html &udon ';h1#hello: hello'

308';h1#hello: hello'

309```

311#### `_` - Run a function

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

315Write an arbitrary function and pass data to it:

317```

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

320```

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

324```

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

326301

327```

329#### `+` `-` - HTTP requests

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

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

334JSON `"hi"` in the body.

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

337JSON `"hi"` in the body.

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

341#### `+` - Generators

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

344in `gen/`.

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

347the code needed to log into your ship remotely.

349```

350~your-urbit:dojo> +code

351fintyr-haldet-fassev-solhex

352```

354### Variables

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

357a few reserved names that have special uses.

359#### dir

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

363**Examples:**

365```

366~your-urbit:dojo> =dir %/web

367~your-urbit:dojo> +ls %

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

369```

371#### lib

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

374with `/+`. Read / write.

376**Examples:**

378```

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

380```

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

382```

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

384```

386#### sur

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

389with `/-`. Read / write.

391**Examples:**

393```

394~your-urbit:dojo> /- sole

395```

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

397```

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

399```

401#### now

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

405**Example:**

407```

408~your-urbit:dojo> now

409~2016.3.21..21.10.57..429a

410```

412#### our

414The current urbit ship. Read-only.

416**Example:**

418```

419~your-urbit:dojo> our

420~your-urbit

421```

423#### eny

425512 bits of entropy. Read-only.

427**Example:**

429```

430~your-urbit:dojo> eny

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

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

434```

436## Troubleshooting

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

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

440and your Dojo will end the blocked command.