git.iko.soy/urbit.org
on c19bc7a help sign in
urbit.org/docs/using/shell.udon
433 lines 8.4 kB history raw
1:- :~ navhome/'/docs/'
2 navuptwo/'true'
3 next/'true'
4 sort/'6'
5 title/'Shell (Dojo)'
6 ==
7;>
9# Shell (Dojo)
12The Dojo is our shell; it processes system commands and returns output. It's a
13good place to quickly experiment with Urbit. On the surface the Dojo is just a
14Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
15data in Urbit.
18## Quickstart
20You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
21commands.
23##### Math
25Evaluate a Hoon expression (whitespace matters):
27```
28~your-urbit:dojo> (add 2 2)
29~your-urbit:dojo> %+ add 2 2
30```
32Tall-form Hoon may require multiple lines:
34```
35~your-urbit:dojo> %+ add
36~your-urbit:dojo< 2
37~your-urbit:dojo< 2
38```
40Hoon uses something called [the subject](../../tutorials/hoon-ch1/hoon-ch1-3).
41The Dojo has its own subject, and that's where Hoon's equivalent of variables,
42called faces, are stored.
44Use `=var` to save faces to the Dojo subject.
46```
47~your-urbit:dojo> =foo (add 2 2)
48```
50Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
51face in a `.hoon` file in this way.
53##### System Commands
55Use `=dir` to set the current working directory:
57```
58~your-urbit:dojo> =dir %/web
59```
61(`%` represents your current directory. For a complete explanation on urbit
62paths, see the [filesystem section](/docs/using/filesystem))
64Generators (files in `/gen`) are run with `+`:
66```
67~your-urbit:dojo> +hello 'world'
68```
70Save output to a file in `%clay` with `*`:
72```
73~your-urbit:dojo> *some/file/path/hoon 'hello world'
74```
76Run system commands from `:hood`, like `reload`, using `|`:
78```
79~your-urbit:dojo> |reload %eyre
80```
82### Generators
84Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
85directory. Many Dojo commands exist in the form of generators. The syntax for
86running a generator is `+genname` for a generator saved as `genname.hoon`.
88##### +cat
90Accepts a path and displays the file. Similar to Unix `cat`.
92```
93~your-urbit:dojo> +cat %/gen/curl/hoon
94```
96##### +code
98Generates a code that is used to remotely log into your ship. No
99arguments.
101```
102~your-urbit:dojo> +code
103```
105##### +curl
107Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.
109```
110~your-urbit:dojo> +curl "http://nyt.com"
111```
113##### +hello
115Just prints the argument. Accepts a `@ta`.
117```
118~your-urbit:dojo> +hello 'mars'
119```
121##### +ls
123Similar to Unix `ls`. Accepts a path.
125```
126~your-urbit:dojo> +ls %/web
127~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
128```
130##### +moon
132Generates a random moon from a planet. No arguments.
134```
135~your-urbit:dojo> +moon
136```
138##### +solid
140Compile the current state of the kernel and output a
141noun. Usually downloaded to a file in unix. No arguments.
143```
144~your-urbit:dojo> .urbit/pill +solid
145```
147##### +test
149Testrunner. Can test multiple generators at once, conventionally ones
150in the `/test` folder. Takes a path.
152```
153~your-urbit:dojo> +test /lib
154```
156##### +ticket
158Generate a ticket for an urbit ship. Takes an urbit name (`@p`).
161```
162~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
163```
165##### +tree
167Generate a recursive directory listing. Takes a path.
169```
170~your-urbit:dojo> +tree %/web
171```
173### Hood
175The hood is the system daemon. See `gen/hood` and `app/hood`.
177`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
178an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
180```
181~your-urbit:dojo> |hi ~binzod "you there?"
182```
184`|link` / `|unlink` - Link / unlink a remote app. Accepts an
185Urbit name and an app name.
187```
188~your-urbit:dojo> |link ~talsur-todres %octo
189```
191`|mass` - Prints the current memory usage of all the kernel modules.
192No arguments.
194```
195~your-urbit:dojo> |mass
196```
198`|reload` - Reloads a kernel module (vane) from source. Accepts any
199number of vane names.
201```
202~your-urbit:dojo> |reload %clay %eyre
203```
205*`|reset`* - Reloads `hoon.hoon` and all modules. No arguments.
207```
208~your-urbit:dojo> |reset
209```
211*`|start`* - Starts an app. Accepts an app name.
213```
214~your-urbit:dojo> |start %curl
215```
217---
219## Manual
221;h3(class "first child")
222Sources and sinks
223==
225A Dojo command is either a *source* or a *sink*. A source is just something
226that can be printed to your console or the result of some computation. A
227sink is an *effect*: a change to the filesystem, a network message, a
228change to your environment, or typed message to an app.
230Sources can be chained together, but we can only produce one effect per
231command.
233### Sinks
235##### `=` - Set variable
237Set any environment variable:
239```
240~your-urbit:dojo> =foo 42
241~your-urbit:dojo> (add 2 foo)
24344
244```
246Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
247variable in a `.hoon` file in this way.
249##### Special Variables
251There are a few special variables that the Dojo maintains.
253##### `:` - Send to app
255`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
257Send a `helm-hi` message to `hood`:
259```
260~your-urbit:dojo> :hood &helm-hi 'hi'
261```
263Apps usually expect marked data, so `&` is often used here.
265##### `*` - Save in `%clay`
267Save a new `.udon` ([Udon](/docs/tutorials/udon)) file in `web`:
269```
270~your-urbit:dojo> *%/web/foo/udon '# hello'
271```
273The last component of the path is expected to be the mark (or mime
274type).
276##### `.` - Export to Unix
278Export a noun to Unix with `.`:
280```
281~your-urbit:dojo> .foo/bar/baz (add 2 2)
282```
284Which creates a file at `pier/.urb/put/foo/bar.baz`.
286This is very often used with `+solid`:
288```
289~your-urbit:dojo> .urbit/pill +solid
290```
292Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
294### Sources
296##### `&` - Mark conversion
298Convert between marks using `&`:
300```
301~your-urbit:dojo> &html &md '# hello'
302'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
303```
305##### `_` - Run a function
307Use `_` to run a gate (or function):
309Write an arbitrary function and pass data to it:
311```
312~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
314```
316Use a function to get the status code from an http request:
318```
319~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
320301
321```
323##### `+` `-` - HTTP requests
325`+http[s]://example.com` - sends a GET request
327`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
328JSON `"hi"` in the body.
330`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
331JSON `"hi"` in the body.
333Note that the first of these is a source while the last two are sinks.
335##### `+` - Generators
337Generators are simple Hoon scripts loaded from the filesystem. They live
338in `gen/`.
340An example of a generator that is built into your urbit is `+code`. It produces
341the code needed to log into your ship remotely.
343```
344~your-urbit:dojo> +code
345fintyr-haldet-fassev-solhex
346```
348### Variables
350You can use `=` to set an environment variable in Dojo, but there are
351a few reserved names that have special uses.
353##### dir
355Current working `%clay` desk and revision. Read / write.
357*Examples:*
359```
360~your-urbit:dojo> =dir %/web
361~your-urbit:dojo> +ls %
362404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
363```
365##### lib
367Current set of libraries (`/lib`) in your environment. Can be set
368with `/+`. Read / write.
370*Examples:*
372```
373~your-urbit:dojo> /+ react
374~your-urbit:dojo> :: now we can use arms from lib/react.hoon
375~your-urbit:dojo> (react-vale:react %div)
376```
378##### sur
380Current set of structures (`/sur`) in your environment. Can be set
381with `/-`. Read / write.
383*Examples:*
385```
386~your-urbit:dojo> /- sole
387~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
388~your-urbit:dojo> `sole-effect:sole`[%bel ~]
389```
391##### now
393The current (128-bit `@da`) time. Read-only.
395*Example:*
397```
398~your-urbit:dojo> now
399:: produces
400~2016.3.21..21.10.57..429a
401```
403##### our
405The current urbit ship. Read-only.
407*Example:*
409```
410~your-urbit:dojo> our
411:: produces
412~your-urbit
413```
415##### eny
417512 bits of entropy. Read-only.
419*Example:*
421```
422~your-urbit:dojo> eny
423:: produces
424\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
425 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
426\/
427```
429## Troubleshooting
431If you encounter `%dy-edit-busy` while entering commands, it is
432because your Dojo is blocked on a timer or an HTTP request. Type backspace
433and your Dojo will end the blocked command.