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

git.iko.soy/urbit.org

on 1237dc4 help sign in

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

415 lines 8.2 kB history raw

1+++

2title = "Shell"

3template = "page_indiced.html"

4weight = 2

5+++

7## Shell {#using-the-shell}

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

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

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

12data in Urbit.

14### Quickstart

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

17commands.

19#### Math

21Evaluate a Hoon expression (whitespace matters):

23```

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

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

26```

28Tall-form Hoon may require multiple lines:

30```

31~your-urbit:dojo> %+ add

32~your-urbit:dojo< 2

33~your-urbit:dojo< 2

34```

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

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

38called faces, are stored.

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

42```

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

44```

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

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

49#### System commands

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

53```

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

55```

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

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

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

62```

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

64```

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

68```

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

70```

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

74```

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

76```

78### Generators

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

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

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

84#### `+cat`

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

88```

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

90```

92#### `+code`

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

95arguments.

97```

98~your-urbit:dojo> +code

99```

100

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

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

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

104

105#### `+curl`

106

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

108

109```

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

111```

112

113#### `+hello`

114

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

116

117```

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

119```

120

121#### `+ls`

122

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

124

125```

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

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

128```

129

130#### `+solid`

131

132Compile the current state of the kernel and output a

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

134

135```

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

137```

138

139#### `+test`

140

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

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

143

144```

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

146```

147

148#### `+ticket`

149

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

151

152

153```

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

155```

156

157#### `+tree`

158

159Generate a recursive directory listing. Takes a path.

160

161```

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

163```

164

165### Hood

166

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

168

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

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

171

172```

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

174```

175

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

177Urbit name and an app name.

178

179```

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

181```

182

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

184No arguments.

185

186```

187~your-urbit:dojo> |mass

188```

189

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

191number of vane names.

192

193```

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

195```

196

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

198

199```

200~your-urbit:dojo> |reset

201```

202

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

204

205```

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

207```

208

209---

210

211### Dojo manual

212

213#### Sources and sinks

214

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

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

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

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

219

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

221command.

222

223#### Sinks

224

225#### `=` - Set variable

226

227Set any environment variable:

228

229```

230~your-urbit:dojo> =foo 42

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

232

23344

234```

235

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

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

238

239#### Special variables

240

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

242

243#### `:` - Send to app

244

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

246

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

248

249```

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

251```

252

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

254

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

256

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

258

259```

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

261```

262

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

264type).

265

266#### `.` - Export to Unix

267

268Export a noun to Unix with `.`:

269

270```

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

272```

273

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

275

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

277

278```

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

280```

281

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

283

284### Sources

285

286#### `_` - Run a function

287

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

289

290Write an arbitrary function and pass data to it:

291

292```

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

2949

295```

296

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

298

299```

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

301301

302```

303

304#### `+` `-` - HTTP requests

305

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

307

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

309JSON `"hi"` in the body.

310

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

312JSON `"hi"` in the body.

313

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

315

316#### `+` - Generators

317

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

319in `gen/`.

320

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

322the code needed to log into your ship remotely.

323

324```

325~your-urbit:dojo> +code

326fintyr-haldet-fassev-solhex

327```

328

329### Variables

330

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

332a few reserved names that have special uses.

333

334#### `dir`

335

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

337

338**Examples:**

339

340```

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

342~your-urbit:dojo> +ls %

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

344```

345

346#### `lib`

347

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

349with `/+`. Read / write.

350

351**Examples:**

352

353```

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

355```

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

357```

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

359```

360

361#### `sur`

362

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

364with `/-`. Read / write.

365

366**Examples:**

367

368```

369~your-urbit:dojo> /- sole

370```

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

372```

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

374```

375

376#### `now`

377

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

379

380**Example:**

381

382```

383~your-urbit:dojo> now

384~2016.3.21..21.10.57..429a

385```

386

387#### `our`

388

389The current urbit ship. Read-only.

390

391**Example:**

392

393```

394~your-urbit:dojo> our

395~your-urbit

396```

397

398#### `eny`

399

400512 bits of entropy. Read-only.

401

402**Example:**

403

404```

405~your-urbit:dojo> eny

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

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

408\/

409```

410

411### Troubleshooting

412

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

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

415and your Dojo will end the blocked command.