git.iko.soy/urbit.org
on 3a197af help sign in
urbit.org/docs/using/shell.md
312 lines 7.3 kB history raw
1---
2navhome: /docs/
3navuptwo: true
4next: true
5sort: 6
6title: Shell (Dojo)
7---
9# Shell (Dojo)
11<div class="row">
13<div class="col-md-8">
15The Dojo is the place to quickly experiment with Urbit. On the
16surface the Dojo is just a Hoon REPL. On the inside, the Dojo is a
17system for operating on and transforming data in Urbit.
19</div>
21</div>
23## Quickstart
25Evaluate a hoon expression (whitespace matters):
27 ~your-urbit:dojo> (add 2 2)
28 ~your-urbit:dojo> %+ add 2 2
30Tall form Hoon may require multiple lines:
32 ~your-urbit:dojo> %+ add
33 ~your-urbit:dojo< 2
34 ~your-urbit:dojo< 2
36Use `=var` to save a shell variable:
38 ~your-urbit:dojo> =foo (add 2 2)
40Use `=dir` to set the current working directory:
42 ~your-urbit:dojo> =dir %/web
44(`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/filesystem))
46Generators (files in `/gen`) are run with `+`:
48 ~your-urbit:dojo> +hello 'world'
50Save output to a file in `%clay` with `*`:
52 ~your-urbit:dojo> *some/file/path/hoon 'hello world'
54Run system commands from `:hood`, like `reload`, using `|`:
56 ~your-urbit:dojo> |reload %eyre
58### Generators
60**`+cat`** - Similar to Unix `cat`. Accepts a path.
62 ~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon
65**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
67 ~your-urbit:dojo> +curl "http://nyt.com"
69**`+hello`** - Just prints the argument. Accepts a `@ta`.
71 ~your-urbit:dojo> +hello 'mars'
73**`+ls`** - Similar to Unix `ls`. Accepts a path.
75 ~your-urbit:dojo> +ls %/web
76 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
78**`+moon`** - Generate a random moon from a planet. No arguments.
80 ~your-urbit:dojo> +moon
82**`+solid`** - Compile the current state of the kernel and output a
83noun. Usually downloaded to a file in unix. No arguments.
85 ~your-urbit:dojo> .urbit/pill +solid
87**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name
88(`@p`).
90 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
92**`+tree`** - Generate a recursive directory listing. Takes a path.
94 ~your-urbit:dojo> +tree %/web
96### Hood
98The hood is the system daemon. See `gen/hood` and `app/hood`.
100**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts
101an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
103 ~your-urbit:dojo> |hi ~binzod "you there?"
105**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an
106Urbit name and an app name.
108 ~your-urbit:dojo> |link ~talsur-todres %octo
110**`|mass`** - Prints the current memory usage of all the kernel modules.
111No arguments.
113 ~your-urbit:dojo> |mass
115**`|reload`** - Reloads a kernel module (vane) from source. Accepts any
116number of vane names.
118 ~your-urbit:dojo> |reload %clay %eyre
120**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
122 ~your-urbit:dojo> |reset
124**`|start`** - Starts an app. Accepts an app name.
126 ~your-urbit:dojo> |start %curl
128## Manual
130<h3 class="first child">
131Sources and sinks
132</h3>
134A dojo command is either a source or a sink. A source is just something
135that can be printed to your console or the result of some computation. A
136sink is an *effect*: a change to the filesystem, a network message, a
137change to your environment, or typed message to an app.
139Sources can be chained together, but we can only produce one effect per
140command.
142### Sinks
144#### `=` - Set variable
146Set any envronment variable:
148 ~your-urbit:dojo> =foo 42
149 ~your-urbit:dojo> (add 2 foo)
151 44
153(There are a few special variables that the dojo maintains. See below.)
155#### `:` - Send to app
157`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
159Send a `helm-hi` message to `hood`:
161 ~your-urbit:dojo> :hood &helm-hi 'hi'
163App usually expect marked data, so `&` is often used here.
165#### `*` - Save in `%clay`
167Save a new `md` file in `web`:
169 ~your-urbit:dojo> *%/web/foo/md '# hello'
171The last component of the path is expected to be the mark (or mime
172type).
174#### `.` - Export to Unix
176Export a noun to Unix with `.`:
178 ~your-urbit:dojo> .foo/bar/baz (add 2 2)
180Which creates a file at `pier/.urb/put/foo/bar.baz`.
182This is very often used with `+solid`:
184 ~your-urbit:dojo> .urbit/pill +solid
186Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
188### Sources
190#### `&` - Mark conversion
192Convert between marks using `&`:
194 ~your-urbit:dojo> &html &md '# hello'
195 :: produces
196 '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
198#### `_` - Run a function
200Use `_` to run a gate (or function):
202 :: assign an arbitrary function and pass data to it
203 ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
204 :: produces
205 9
206 :: use a function to get the status code from an http request
207 ~your-urbit:dojo> _|=({p/@ud q/* r/*} p) +http://google.com
208 :: produces
209 301
211#### `+` `-` - HTTP requests
213`+http[s]://example.com` - sends a GET request
215`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
216JSON `"hi"` in the body.
218`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
219JSON `"hi"` in the body.
221Note that the first of these is a source while the last two are sinks.
223#### `+` - Generators
225Generators are simple hoon scripts loaded from the filesystem. They live
226in `gen/`.
228Create a random moon (from any planet):
230 ~your-urbit:dojo> +moon
231 :: produces
232 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
234### Variables
236You can use `=` to set an environment variable in Dojo, but there are
237a few reserved names that have special uses.
239#### `dir`
241Current working `%clay` desk and revision. Read / write.
243**Examples:**
245 ~your-urbit:dojo> =dir %/web
246 ~your-urbit:dojo> +ls %
248 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
250#### `lib`
252Current set of libraries (`/lib`) in your environment. Can also be set
253with `/+`. Read / write.
255**Examples:**
257 ~your-urbit:dojo> =lib ~[[%react ~]]
258 ~your-urbit:dojo> :: this also works:
259 ~your-urbit:dojo> /+ react
260 ~your-urbit:dojo> :: now we can use arms from lib/react.hoon
261 ~your-urbit:dojo> (react-vale:react %div)
263#### `sur`
265Current set of structures (`/sur`) in your environment. Can also be set
266with `/-`. Read / write.
268**Examples:**
270 ~your-urbit:dojo> =sur ~[[%sole ~]]
271 ~your-urbit:dojo> :: this also works:
272 ~your-urbit:dojo> /- sole
273 ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
274 ~your-urbit:dojo> `sole-effect:sole`[%bel ~]
276#### `now`
278The current (128-bit `@da`) time. Read-only.
280**Example:**
282 ~your-urbit:dojo> now
283 :: produces
284 ~2016.3.21..21.10.57..429a
286#### `our`
288The current urbit plot. Read-only.
290**Example:**
292 ~your-urbit:dojo> our
293 :: produces
294 ~your-urbit
296#### `eny`
298256 bits of entropy. Read-only.
300**Example:**
302 ~your-urbit:dojo> eny
303 :: produces
304 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
307## Troubleshooting
309If you encounter `%dy-edit-busy` while entering commands, it is
310because your dojo is blocked on a timer or an http request. Type backspace
311and your dojo will end the blocked command.