git.iko.soy/urbit.org
on 099c808 help sign in
urbit.org/docs/using/shell.umd
377 lines 7.3 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 the place to quickly experiment with Urbit. On the
15surface the Dojo is just a Hoon REPL. On the inside, the Dojo is a
16system for operating on and transforming data in Urbit.
18 ==
19==
21## Quickstart
23Evaluate a hoon expression (whitespace matters):
25```
26~your-urbit:dojo> (add 2 2)
27~your-urbit:dojo> %+ add 2 2
28```
30Tall form Hoon may require multiple lines:
32```
33~your-urbit:dojo> %+ add
34~your-urbit:dojo< 2
35~your-urbit:dojo< 2
36```
38Use `=var` to save a shell variable:
40```
41~your-urbit:dojo> =foo (add 2 2)
42```
44Use `=dir` to set the current working directory:
46```
47~your-urbit:dojo> =dir %/web
48```
50(`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/filesystem))
52Generators (files in `/gen`) are run with `+`:
54```
55~your-urbit:dojo> +hello 'world'
56```
58Save output to a file in `%clay` with `*`:
60```
61~your-urbit:dojo> *some/file/path/hoon 'hello world'
62```
64Run system commands from `:hood`, like `reload`, using `|`:
66```
67~your-urbit:dojo> |reload %eyre
68```
70### Generators
72**`+cat`** - Similar to Unix `cat`. Accepts a path.
74```
75~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon
76```
78**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
80```
81~your-urbit:dojo> +curl "http://nyt.com"
82```
84**`+hello`** - Just prints the argument. Accepts a `@ta`.
86```
87~your-urbit:dojo> +hello 'mars'
88```
90**`+ls`** - Similar to Unix `ls`. Accepts a path.
92```
93~your-urbit:dojo> +ls %/web
94~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
95```
97**`+moon`** - Generate a random moon from a planet. No arguments.
99```
100~your-urbit:dojo> +moon
101```
103**`+solid`** - Compile the current state of the kernel and output a
104noun. Usually downloaded to a file in unix. No arguments.
106```
107~your-urbit:dojo> .urbit/pill +solid
108```
110**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name
111(`@p`).
113```
114~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
115```
117**`+tree`** - Generate a recursive directory listing. Takes a path.
119```
120~your-urbit:dojo> +tree %/web
121```
123### Hood
125The hood is the system daemon. See `gen/hood` and `app/hood`.
127**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts
128an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
130```
131~your-urbit:dojo> |hi ~binzod "you there?"
132```
134**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an
135Urbit name and an app name.
137```
138~your-urbit:dojo> |link ~talsur-todres %octo
139```
141**`|mass`** - Prints the current memory usage of all the kernel modules.
142No arguments.
144```
145~your-urbit:dojo> |mass
146```
148**`|reload`** - Reloads a kernel module (vane) from source. Accepts any
149number of vane names.
151```
152~your-urbit:dojo> |reload %clay %eyre
153```
155**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
157```
158~your-urbit:dojo> |reset
159```
161**`|start`** - Starts an app. Accepts an app name.
163```
164~your-urbit:dojo> |start %curl
165```
167## Manual
169;h3(class "first child")
170Sources and sinks
171==
173A dojo command is either a source or a sink. A source is just something
174that can be printed to your console or the result of some computation. A
175sink is an *effect*: a change to the filesystem, a network message, a
176change to your environment, or typed message to an app.
178Sources can be chained together, but we can only produce one effect per
179command.
181### Sinks
183#### `=` - Set variable
185Set any envronment variable:
187```
188~your-urbit:dojo> =foo 42
189~your-urbit:dojo> (add 2 foo)
19144
192```
194(There are a few special variables that the dojo maintains. See below.)
196#### `:` - Send to app
198`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
200Send a `helm-hi` message to `hood`:
202```
203~your-urbit:dojo> :hood &helm-hi 'hi'
204```
206App usually expect marked data, so `&` is often used here.
208#### `*` - Save in `%clay`
210Save a new `md` file in `web`:
212```
213~your-urbit:dojo> *%/web/foo/md '# hello'
214```
216The last component of the path is expected to be the mark (or mime
217type).
219#### `.` - Export to Unix
221Export a noun to Unix with `.`:
223```
224~your-urbit:dojo> .foo/bar/baz (add 2 2)
225```
227Which creates a file at `pier/.urb/put/foo/bar.baz`.
229This is very often used with `+solid`:
231```
232~your-urbit:dojo> .urbit/pill +solid
233```
235Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
237### Sources
239#### `&` - Mark conversion
241Convert between marks using `&`:
243```
244~your-urbit:dojo> &html &md '# hello'
245'<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
246```
248#### `_` - Run a function
250Use `_` to run a gate (or function):
252Write an arbitrary function and pass data to it:
254```
255~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
257```
259Use a function to get the status code from an http request:
261```
262~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
263301
264```
266#### `+` `-` - HTTP requests
268`+http[s]://example.com` - sends a GET request
270`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
271JSON `"hi"` in the body.
273`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
274JSON `"hi"` in the body.
276Note that the first of these is a source while the last two are sinks.
278#### `+` - Generators
280Generators are simple hoon scripts loaded from the filesystem. They live
281in `gen/`.
283Create a random moon (from any planet):
285```
286~your-urbit:dojo> +moon
287"moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
288```
290### Variables
292You can use `=` to set an environment variable in Dojo, but there are
293a few reserved names that have special uses.
295#### `dir`
297Current working `%clay` desk and revision. Read / write.
299**Examples:**
301```
302~your-urbit:dojo> =dir %/web
303~your-urbit:dojo> +ls %
304404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
305```
307#### `lib`
309Current set of libraries (`/lib`) in your environment. Can also be set
310with `/+`. Read / write.
312**Examples:**
314```
315~your-urbit:dojo> =lib ~[[%react ~]]
316~your-urbit:dojo> :: this also works:
317~your-urbit:dojo> /+ react
318~your-urbit:dojo> :: now we can use arms from lib/react.hoon
319~your-urbit:dojo> (react-vale:react %div)
320```
322#### `sur`
324Current set of structures (`/sur`) in your environment. Can also be set
325with `/-`. Read / write.
327**Examples:**
329```
330~your-urbit:dojo> =sur ~[[%sole ~]]
331~your-urbit:dojo> :: this also works:
332~your-urbit:dojo> /- sole
333~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
334~your-urbit:dojo> `sole-effect:sole`[%bel ~]
335```
337#### `now`
339The current (128-bit `@da`) time. Read-only.
341**Example:**
343```
344~your-urbit:dojo> now
345:: produces
346~2016.3.21..21.10.57..429a
347```
349#### `our`
351The current urbit plot. Read-only.
353**Example:**
355```
356~your-urbit:dojo> our
357:: produces
358~your-urbit
359```
361#### `eny`
363256 bits of entropy. Read-only.
365**Example:**
367```
368~your-urbit:dojo> eny
369:: produces
3700v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
371```
373## Troubleshooting
375If you encounter `%dy-edit-busy` while entering commands, it is
376because your dojo is blocked on a timer or an http request. Type backspace
377and your dojo will end the blocked command.