git.iko.soy/urbit.org
on 5ce7d9b help sign in
urbit.org/using/shell.md
425 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### 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)
23544
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](../udon)) 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 `&`:
292```
293~your-urbit:dojo> &html &md '# hello'
294'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
295```
297##### `_` - Run a function
299Use `_` to run a gate (or function):
301Write an arbitrary function and pass data to it:
303```
304~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
306```
308Use a function to get the status code from an http request:
310```
311~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
312301
313```
315##### `+` `-` - HTTP requests
317`+http[s]://example.com` - sends a GET request
319`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
320JSON `"hi"` in the body.
322`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
323JSON `"hi"` in the body.
325Note that the first of these is a source while the last two are sinks.
327##### `+` - Generators
329Generators are simple Hoon scripts loaded from the filesystem. They live
330in `gen/`.
332An example of a generator that is built into your urbit is `+code`. It produces
333the code needed to log into your ship remotely.
335```
336~your-urbit:dojo> +code
337fintyr-haldet-fassev-solhex
338```
340### Variables
342You can use `=` to set an environment variable in Dojo, but there are
343a few reserved names that have special uses.
345##### dir
347Current working `%clay` desk and revision. Read / write.
349**Examples:**
351```
352~your-urbit:dojo> =dir %/web
353~your-urbit:dojo> +ls %
354404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
355```
357##### lib
359Current set of libraries (`/lib`) in your environment. Can be set
360with `/+`. Read / write.
362**Examples:**
364```
365~your-urbit:dojo> /+ react
366~your-urbit:dojo> :: now we can use arms from lib/react.hoon
367~your-urbit:dojo> (react-vale:react %div)
368```
370##### sur
372Current set of structures (`/sur`) in your environment. Can be set
373with `/-`. Read / write.
375**Examples:**
377```
378~your-urbit:dojo> /- sole
379~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
380~your-urbit:dojo> `sole-effect:sole`[%bel ~]
381```
383##### now
385The current (128-bit `@da`) time. Read-only.
387**Example:**
389```
390~your-urbit:dojo> now
391:: produces
392~2016.3.21..21.10.57..429a
393```
395##### our
397The current urbit ship. Read-only.
399**Example:**
401```
402~your-urbit:dojo> our
403:: produces
404~your-urbit
405```
407##### eny
409512 bits of entropy. Read-only.
411**Example:**
413```
414~your-urbit:dojo> eny
415:: produces
416\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
417 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
418\/
419```
421## Troubleshooting
423If you encounter `%dy-edit-busy` while entering commands, it is
424because your Dojo is blocked on a timer or an HTTP request. Type backspace
425and your Dojo will end the blocked command.