git.iko.soy/urbit.org
on 8883702 help sign in
urbit.org/using/shell.md
427 lines 8.3 kB history raw
1+++
2title = "Shell"
3weight = 3
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/arvo/hoon/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 %/web
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```
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;h3(class "first child")
216Sources and sinks
217==
219A Dojo command is either a *source* or a *sink*. A source is just something
220that can be printed to your console or the result of some computation. A
221sink is an *effect*: a change to the filesystem, a network message, a
222change to your environment, or typed message to an app.
224Sources can be chained together, but we can only produce one effect per
225command.
227### Sinks
229##### `=` - Set variable
231Set any environment variable:
233```
234~your-urbit:dojo> =foo 42
235~your-urbit:dojo> (add 2 foo)
23744
238```
240Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
241variable in a `.hoon` file in this way.
243##### Special Variables
245There are a few special variables that the Dojo maintains.
247##### `:` - Send to app
249`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
251Send a `helm-hi` message to `hood`:
253```
254~your-urbit:dojo> :hood &helm-hi 'hi'
255```
257Apps usually expect marked data, so `&` is often used here.
259##### `*` - Save in `%clay`
261Save a new `.udon` ([Udon](../udon)) file in `web`:
263```
264~your-urbit:dojo> *%/web/foo/udon '# hello'
265```
267The last component of the path is expected to be the mark (or mime
268type).
270##### `.` - Export to Unix
272Export a noun to Unix with `.`:
274```
275~your-urbit:dojo> .foo/bar/baz (add 2 2)
276```
278Which creates a file at `pier/.urb/put/foo/bar.baz`.
280This is very often used with `+solid`:
282```
283~your-urbit:dojo> .urbit/pill +solid
284```
286Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
288### Sources
290##### `&` - Mark conversion
292Convert between marks using `&`:
294```
295~your-urbit:dojo> &html &md '# hello'
296'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
297```
299##### `_` - Run a function
301Use `_` to run a gate (or function):
303Write an arbitrary function and pass data to it:
305```
306~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
308```
310Use a function to get the status code from an http request:
312```
313~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
314301
315```
317##### `+` `-` - HTTP requests
319`+http[s]://example.com` - sends a GET request
321`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
322JSON `"hi"` in the body.
324`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
325JSON `"hi"` in the body.
327Note that the first of these is a source while the last two are sinks.
329##### `+` - Generators
331Generators are simple Hoon scripts loaded from the filesystem. They live
332in `gen/`.
334An example of a generator that is built into your urbit is `+code`. It produces
335the code needed to log into your ship remotely.
337```
338~your-urbit:dojo> +code
339fintyr-haldet-fassev-solhex
340```
342### Variables
344You can use `=` to set an environment variable in Dojo, but there are
345a few reserved names that have special uses.
347##### dir
349Current working `%clay` desk and revision. Read / write.
351*Examples:*
353```
354~your-urbit:dojo> =dir %/web
355~your-urbit:dojo> +ls %
356404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
357```
359##### lib
361Current set of libraries (`/lib`) in your environment. Can be set
362with `/+`. Read / write.
364*Examples:*
366```
367~your-urbit:dojo> /+ react
368~your-urbit:dojo> :: now we can use arms from lib/react.hoon
369~your-urbit:dojo> (react-vale:react %div)
370```
372##### sur
374Current set of structures (`/sur`) in your environment. Can be set
375with `/-`. Read / write.
377*Examples:*
379```
380~your-urbit:dojo> /- sole
381~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
382~your-urbit:dojo> `sole-effect:sole`[%bel ~]
383```
385##### now
387The current (128-bit `@da`) time. Read-only.
389*Example:*
391```
392~your-urbit:dojo> now
393:: produces
394~2016.3.21..21.10.57..429a
395```
397##### our
399The current urbit ship. Read-only.
401*Example:*
403```
404~your-urbit:dojo> our
405:: produces
406~your-urbit
407```
409##### eny
411512 bits of entropy. Read-only.
413*Example:*
415```
416~your-urbit:dojo> eny
417:: produces
418\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
419 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
420\/
421```
423## Troubleshooting
425If you encounter `%dy-edit-busy` while entering commands, it is
426because your Dojo is blocked on a timer or an HTTP request. Type backspace
427and your Dojo will end the blocked command.