git.iko.soy/urbit.org
on 5b9c970 help sign in
urbit.org/docs/using/shell.umd
423 lines 8.5 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'6'
5 title/'Shell (Dojo)'
6 ==
7;>
9# Shell (Dojo)
11;div(class "row")
12 ;div(class "col-md-8")
14The Dojo is our shell; it processes system commands and returns output. It's a
15good place to quickly experiment with Urbit. On the surface the Dojo is just a
16Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
17data in Urbit.
19 ==
20==
22## Quickstart
24You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
25commands.
27##### Math
29Evaluate a Hoon expression (whitespace matters):
31```
32~your-urbit:dojo> (add 2 2)
33~your-urbit:dojo> %+ add 2 2
34```
36Tall-form Hoon may require multiple lines:
38```
39~your-urbit:dojo> %+ add
40~your-urbit:dojo< 2
41~your-urbit:dojo< 2
42```
44Hoon uses something called [the subject](/../../tutorials/hoon-ch1/hoon-ch1-3).
45The Dojo has its own subject, and that's where Hoon's equivalent of variables
46are stored.
48Use `=var` to save variable to the Dojo subject.
50```
51~your-urbit:dojo> =foo (add 2 2)
52```
54Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
55variable in a `.hoon` file in this way.
57##### System Commands
60Use `=dir` to set the current working directory:
62```
63~your-urbit:dojo> =dir %/web
64```
66(`%` represents your current directory. For a complete explanation on urbit
67paths, see the [filesystem section](/docs/using/filesystem))
69Generators (files in `/gen`) are run with `+`:
71```
72~your-urbit:dojo> +hello 'world'
73```
75Save output to a file in `%clay` with `*`:
77```
78~your-urbit:dojo> *some/file/path/hoon 'hello world'
79```
81Run system commands from `:hood`, like `reload`, using `|`:
83```
84~your-urbit:dojo> |reload %eyre
85```
87`_See the [Clay](../fileystem) page for more information on system commands.`
89### Generators
91Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
92directory. Many Dojo commands exist in the form of generators. The syntax for
93running a generator is `+genname` for a generator saved as `genname.hoon`.
95`+cat` - Accepts a path and displays the file. Similar to Unix `cat`.
97```
98~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon
99```
101`+code` - Generates a code to remotely log into your ship.
103```
104~your-urbit:dojo> +code
105```
107`+curl` - Retrives data from a URL. Accepts a `tape`. Similar to Unix
108`curl`.
110```
111~your-urbit:dojo> +curl "http://nyt.com"
112```
114`+hello` - Just prints the argument. Accepts a `@ta`.
116```
117~your-urbit:dojo> +hello 'mars'
118```
120`+ls` - Similar to Unix `ls`. Accepts a path.
122```
123~your-urbit:dojo> +ls %/web
124~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
125```
127`+moon` - Generates a random moon from a planet. No arguments.
129```
130~your-urbit:dojo> +moon
131```
133`+solid` - Compile the current state of the kernel and output a
134noun. Usually downloaded to a file in unix. No arguments.
137```
138~your-urbit:dojo> .urbit/pill +solid
139```
141`+test` - Testrunner. Can test multiple generators at once, conventionally ones
142in the `/test` folder. Accepts a path.
144```
145~your-urbit:dojo> +test /lib
146```
148`+ticket` - Generate a ticket for an Urbit plot. Takes an Urbit name
149(`@p`).
152```
153~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
154```
156`+tree` - Generate a recursive directory listing. Takes a path.
158```
159~your-urbit:dojo> +tree %/web
160```
162### Hood
164The hood is the system daemon. See `gen/hood` and `app/hood`.
166`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
167an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
169```
170~your-urbit:dojo> |hi ~binzod "you there?"
171```
173`|link` / `|unlink - Link / unlink a remote app. Accepts an
174Urbit name and an app name.
176```
177~your-urbit:dojo> |link ~talsur-todres %octo
178```
180`|mass` - Prints the current memory usage of all the kernel modules.
181No arguments.
183```
184~your-urbit:dojo> |mass
185```
187`|reload` - Reloads a kernel module (vane) from source. Accepts any
188number of vane names.
190```
191~your-urbit:dojo> |reload %clay %eyre
192```
194**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
196```
197~your-urbit:dojo> |reset
198```
200**`|start`** - Starts an app. Accepts an app name.
202```
203~your-urbit:dojo> |start %curl
204```
206## Manual
208;h3(class "first child")
209Sources and sinks
210==
212A dojo command is either a source or a sink. A source is just something
213that can be printed to your console or the result of some computation. A
214sink is an *effect*: a change to the filesystem, a network message, a
215change to your environment, or typed message to an app.
217Sources can be chained together, but we can only produce one effect per
218command.
220### Sinks
222##### `=` - Set variable
224Set any environment variable:
226```
227~your-urbit:dojo> =foo 42
228~your-urbit:dojo> (add 2 foo)
23044
231```
233Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
234variable in a `.hoon` file in this way.
236#### Special Variables
238There are a few special variables that the dojo maintains.
240#### `:` - Send to app
242`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
244Send a `helm-hi` message to `hood`:
246```
247~your-urbit:dojo> :hood &helm-hi 'hi'
248```
250Apps usually expect marked data, so `&` is often used here.
252#### `*` - Save in `%clay`
254Save a new `md` file in `web`:
256```
257~your-urbit:dojo> *%/web/foo/md '# hello'
258```
260The last component of the path is expected to be the mark (or mime
261type).
263#### `.` - Export to Unix
265Export a noun to Unix with `.`:
267```
268~your-urbit:dojo> .foo/bar/baz (add 2 2)
269```
271Which creates a file at `pier/.urb/put/foo/bar.baz`.
273This is very often used with `+solid`:
275```
276~your-urbit:dojo> .urbit/pill +solid
277```
279Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
281### Sources
283#### `&` - Mark conversion
285Convert between marks using `&`:
287```
288~your-urbit:dojo> &html &md '# hello'
289'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
290```
292#### `_` - Run a function
294Use `_` to run a gate (or function):
296Write an arbitrary function and pass data to it:
298```
299~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
301```
303Use a function to get the status code from an http request:
305```
306~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
307301
308```
310#### `+` `-` - HTTP requests
312`+http[s]://example.com` - sends a GET request
314`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
315JSON `"hi"` in the body.
317`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
318JSON `"hi"` in the body.
320Note that the first of these is a source while the last two are sinks.
322#### `+` - Generators
324Generators are simple hoon scripts loaded from the filesystem. They live
325in `gen/`.
327Create a random moon (from any planet):
329```
330~your-urbit:dojo> +moon
331"moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
332```
334### Variables
336You can use `=` to set an environment variable in Dojo, but there are
337a few reserved names that have special uses.
339#### `dir`
341Current working `%clay` desk and revision. Read / write.
343**Examples:**
345```
346~your-urbit:dojo> =dir %/web
347~your-urbit:dojo> +ls %
348404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
349```
351#### `lib`
353Current set of libraries (`/lib`) in your environment. Can also be set
354with `/+`. Read / write.
356**Examples:**
358```
359~your-urbit:dojo> =lib ~[[%react ~]]
360~your-urbit:dojo> :: this also works:
361~your-urbit:dojo> /+ react
362~your-urbit:dojo> :: now we can use arms from lib/react.hoon
363~your-urbit:dojo> (react-vale:react %div)
364```
366#### `sur`
368Current set of structures (`/sur`) in your environment. Can also be set
369with `/-`. Read / write.
371**Examples:**
373```
374~your-urbit:dojo> =sur ~[[%sole ~]]
375~your-urbit:dojo> :: this also works:
376~your-urbit:dojo> /- sole
377~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
378~your-urbit:dojo> `sole-effect:sole`[%bel ~]
379```
381#### `now`
383The current (128-bit `@da`) time. Read-only.
385**Example:**
387```
388~your-urbit:dojo> now
389:: produces
390~2016.3.21..21.10.57..429a
391```
393#### `our`
395The current urbit plot. Read-only.
397**Example:**
399```
400~your-urbit:dojo> our
401:: produces
402~your-urbit
403```
405#### `eny`
407512 bits of entropy. Read-only.
409**Example:**
411```
412~your-urbit:dojo> eny
413:: produces
414\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
415 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
416\/
417```
419## Troubleshooting
421If you encounter `%dy-edit-busy` while entering commands, it is
422because your dojo is blocked on a timer or an http request. Type backspace
423and your dojo will end the blocked command.