git.iko.soy/urbit.org
on bdf9204 help sign in
urbit.org/docs/using/shell.md
301 lines 7.3 kB history raw
1---
2navhome: '/docs'
3next: True
4sort: 5
5title: 'Shell (:dojo)'
6---
8# Shell (`:dojo`)
10<div class="row">
11<div class="col-md-8">
12The `:dojo` is the place to quickly experiment with Urbit. On the surface the
13`:dojo` is just a Hoon REPL. On the inside, the `:dojo` is a system for
14operating on and transforming data in Urbit.
16</div>
17</div>
18## Quickstart
20Evaluate a hoon expression (whitespace matters):
22 ~your-urbit:dojo> (add 2 2)
23 ~your-urbit:dojo> %+ add 2 2
25Tall form Hoon may require multiple lines:
27 ~your-urbit:dojo> %+ add
28 ~your-urbit:dojo< 2
29 ~your-urbit:dojo< 2
31Use `=var` to save a shell variable:
33 ~your-urbit:dojo> =foo (add 2 2)
35Use `=dir` to set the current working directory:
37 ~your-urbit:dojo> =dir %/web
39(`%` represents your current directory. For a complete explanation on urbit
40paths, see the [filesystem section](/docs/using/filesystem))
42Generators (files in `/gen`) are run with `+`:
44 ~your-urbit:dojo> +hello 'world'
46Save output to a file in `%clay` with `*`:
48 ~your-urbit:dojo> *some/file/path/hoon 'hello world'
50Run system commands from `:hood`, like `reload`, using `|`:
52 ~your-urbit:dojo> |reload %eyre
54### Generators
56**`+cat`** - Similar to Unix `cat`. Accepts a path.
58 ~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon
60**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
62 ~your-urbit:dojo> +curl "http://nyt.com"
64**`+hello`** - Just prints the argument. Accepts a `@ta`.
66 ~your-urbit:dojo> +hello 'mars'
68**`+ls`** - Similar to Unix `ls`. Accepts a path.
70 ~your-urbit:dojo> +ls %/web
71 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
73**`+moon`** - Generate a random moon from a planet. No arguments.
75 ~your-urbit:dojo> +moon
77**`+solid`** - Compile the current state of the kernel and output a noun.
78Usually downloaded to a file in unix. No arguments.
80 ~your-urbit:dojo> .urbit/pill +solid
82**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
84 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
86**`+tree`** - Generate a recursive directory listing. Takes a path.
88 ~your-urbit:dojo> +tree %/web
90### Hood
92The hood is the system daemon. See `gen/hood` and `app/hood`.
94**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts an urbit
95name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
97 ~your-urbit:dojo> |hi ~binzod "you there?"
99**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name
100and an app name.
102 ~your-urbit:dojo> |link ~talsur-todres %octo
104**`|mass`** - Prints the current memory usage of all the kernel modules. No
105arguments.
107 ~your-urbit:dojo> |mass
109**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number
110of vane names.
112 ~your-urbit:dojo> |reload %clay %eyre
114**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
116 ~your-urbit:dojo> |reset
118**`|start`** - Starts an app. Accepts an app name.
120 ~your-urbit:dojo> |start %curl
122## Manual
124<h3 class="first child">
125Sources and sinks
126</h3>
127A dojo command is either a source or a sink. A source is just something that can
128be printed to your console or the result of some computation. A sink is an
129*effect*: a change to the filesystem, a network message, a change to your
130environment, or typed message to an app.
132Sources can be chained together, but we can only produce one effect per command.
134### Sinks
136#### `=` - Set variable
138Set any envronment variable:
140 ~your-urbit:dojo> =foo 42
141 ~your-urbit:dojo> (add 2 foo)
143 44
145(There are a few special variables that the dojo maintains. See below.)
147#### `:` - Send to app
149`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
151Send a `helm-hi` message to `hood`:
153 ~your-urbit:dojo> :hood &helm-hi 'hi'
155App usually expect marked data, so `&` is often used here.
157#### `*` - Save in `%clay`
159Save a new `md` file in `web`:
161 ~your-urbit:dojo> *%/web/foo/md '# hello'
163The last component of the path is expected to be the mark (or mime type).
165#### `.` - Export to Unix
167Export a noun to Unix with `.`:
169 ~your-urbit:dojo> .foo/bar/baz (add 2 2)
171Which creates a file at `pier/.urb/put/foo/bar.baz`.
173This is very often used with `+solid`:
175 ~your-urbit:dojo> .urbit/pill +solid
177Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
179### Sources
181#### `&` - Mark conversion
183Convert between marks using `&`:
185 ~your-urbit:dojo> &html &md '# hello'
186 :: produces
187 '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
189#### `_` - Run a function
191Use `_` to run a gate (or function):
193 :: assign an arbitrary function and pass data to it
194 ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
195 :: produces
196 9
197 :: use a function to get the status code from an http request
198 ~your-urbit:dojo> _|=({p/@ud q/* r/*} p) +http://google.com
199 :: produces
200 301
202#### `+` `-` - HTTP requests
204`+http[s]://example.com` - sends a GET request
206`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the JSON
207`"hi"` in the body.
209`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON
210`"hi"` in the body.
212Note that the first of these is a source while the last two are sinks.
214#### `+` - Generators
216Generators are simple hoon scripts loaded from the filesystem. They live in
217`gen/`.
219Create a random moon (from any planet):
221 ~your-urbit:dojo> +moon
222 :: produces
223 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
225### Variables
227You can use `=` to set an environment variable in `:dojo`, but there are a few
228reserved names that have special uses.
230#### `dir`
232Current working `%clay` desk and revision. Read / write.
234**Examples:**
236 ~your-urbit:dojo> =dir %/web
237 ~your-urbit:dojo> +ls %
239 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
241#### `lib`
243Current set of libraries (`/lib`) in your environment. Can also be set with
244`/+`. Read / write.
246**Examples:**
248 ~your-urbit:dojo> =lib ~[[%react ~]]
249 ~your-urbit:dojo> :: this also works:
250 ~your-urbit:dojo> /+ react
251 ~your-urbit:dojo> :: now we can use arms from lib/react.hoon
252 ~your-urbit:dojo> (react-vale:react %div)
254#### `sur`
256Current set of structures (`/sur`) in your environment. Can also be set with
257`/-`. Read / write.
259**Examples:**
261 ~your-urbit:dojo> =sur ~[[%sole ~]]
262 ~your-urbit:dojo> :: this also works:
263 ~your-urbit:dojo> /- sole
264 ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
265 ~your-urbit:dojo> `sole-effect:sole`[%bel ~]
267#### `now`
269The current (128-bit `@da`) time. Read-only.
271**Example:**
273 ~your-urbit:dojo> now
274 :: produces
275 ~2016.3.21..21.10.57..429a
277#### `our`
279The current urbit plot. Read-only.
281**Example:**
283 ~your-urbit:dojo> our
284 :: produces
285 ~your-urbit
287#### `eny`
289256 bits of entropy. Read-only.
291**Example:**
293 ~your-urbit:dojo> eny
294 :: produces
295 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
297## Troubleshooting
299If you encounter `%dy-edit-busy` while entering commands, it is because your
300dojo is blocked on a timer or an http request. Type backspace and your dojo will
301end the blocked command.