git.iko.soy/urbit.org
on 8f5fef2 help sign in
urbit.org/docs/using/shell.md
303 lines 7.1 kB history raw
1---
2navhome: '/docs'
3next: True
4sort: 5
5title: Shell (:dojo)
6---
8# Shell (`:dojo`)
10<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</div>
20</div>
22## Quickstart
24Evaluate a hoon expression (whitespace matters):
26 ~your-urbit:dojo> (add 2 2)
27 ~your-urbit:dojo> %+ add 2 2
29Tall form Hoon may require multiple lines:
31 ~your-urbit:dojo> %+ add
32 ~your-urbit:dojo< 2
33 ~your-urbit:dojo< 2
35Use `=var` to save a shell variable:
37 ~your-urbit:dojo> =foo (add 2 2)
39Use `=dir` to set the current working directory:
41 ~your-urbit:dojo> =dir %/web
43(`%` represents your current directory. For a complete explanation on urbit paths, see the [filesystem section](/docs/using/filesystem))
45Generators (files in `/gen`) are run with `+`:
47 ~your-urbit:dojo> +hello 'world'
49Save output to a file in `%clay` with `*`:
51 ~your-urbit:dojo> *some/file/path/hoon 'hello world'
53Run system commands from `:hood`, like `reload`, using `|`:
55 ~your-urbit:dojo> |reload %eyre
57### Generators
59**`+cat`** - Similar to Unix `cat`. Accepts a path.
61 ~your-urbit:dojo> +cat /~talsur-todres/home/gen/curl/hoon
64**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
66 ~your-urbit:dojo> +curl "http://nyt.com"
68**`+hello`** - Just prints the argument. Accepts a `@ta`.
70 ~your-urbit:dojo> +hello 'mars'
72**`+ls`** - Similar to Unix `ls`. Accepts a path.
74 ~your-urbit:dojo> +ls %/web
75 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
77**`+moon`** - Generate a random moon from a planet. No arguments.
79 ~your-urbit:dojo> +moon
81**`+solid`** - Compile the current state of the kernel and output a
82noun. Usually downloaded to a file in unix. No arguments.
84 ~your-urbit:dojo> .urbit/pill +solid
86**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name
87(`@p`).
89 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
91**`+tree`** - Generate a recursive directory listing. Takes a path.
93 ~your-urbit:dojo> +tree %/web
95### Hood
97The hood is the system daemon. See `gen/hood` and `app/hood`.
99**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts
100an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
102 ~your-urbit:dojo> |hi ~binzod "you there?"
104**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an
105Urbit name and an app name.
107 ~your-urbit:dojo> |link ~talsur-todres %octo
109**`|mass`** - Prints the current memory usage of all the kernel modules.
110No arguments.
112 ~your-urbit:dojo> |mass
114**`|reload`** - Reloads a kernel module (vane) from source. Accepts any
115number of vane names.
117 ~your-urbit:dojo> |reload %clay %eyre
119**`|reset`** - Reloads `hoon.hoon` and all modules. No arguments.
121 ~your-urbit:dojo> |reset
123**`|start`** - Starts an app. Accepts an app name.
125 ~your-urbit:dojo> |start %curl
127## Manual
129<h3 class="first child">
130Sources and sinks
131</h3>
133A dojo command is either a source or a sink. A source is just something
134that can be printed to your console or the result of some computation. A
135sink is an *effect*: a change to the filesystem, a network message, a
136change to your environment, or typed message to an app.
138Sources can be chained together, but we can only produce one effect per
139command.
141### Sinks
143#### `=` - Set variable
145Set any envronment variable:
147 ~your-urbit:dojo> =foo 42
148 ~your-urbit:dojo> (add 2 foo)
150 44
152(There are a few special variables that the dojo maintains. See below.)
154#### `:` - Send to app
156`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
158Send a `helm-hi` message to `hood`:
160 ~your-urbit:dojo> :hood &helm-hi 'hi'
162App usually expect marked data, so `&` is often used here.
164#### `*` - Save in `%clay`
166Save a new `md` file in `web`:
168 ~your-urbit:dojo> *%/web/foo/md '# hello'
170The last component of the path is expected to be the mark (or mime
171type).
173#### `.` - Export to Unix
175Export a noun to Unix with `.`:
177 ~your-urbit:dojo> .foo/bar/baz (add 2 2)
179Which creates a file at `pier/.urb/put/foo/bar.baz`.
181This is very often used with `+solid`:
183 ~your-urbit:dojo> .urbit/pill +solid
185Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
187### Sources
189#### `&` - Mark conversion
191Convert between marks using `&`:
193 ~your-urbit:dojo> &html &md '# hello'
194 :: produces
195 '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
197#### `_` - Run a function
199Use `_` to run a gate (or function):
201 :: assign an arbitrary function and pass data to it
202 ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
203 :: produces
204 9
205 :: use a function to get the status code from an http request
206 ~your-urbit:dojo> _|=({p/@ud q/* r/*} p) +http://google.com
207 :: produces
208 301
210#### `+` `-` - HTTP requests
212`+http[s]://example.com` - sends a GET request
214`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
215JSON `"hi"` in the body.
217`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
218JSON `"hi"` in the body.
220Note that the first of these is a source while the last two are sinks.
222#### `+` - Generators
224Generators are simple hoon scripts loaded from the filesystem. They live
225in `gen/`.
227Create a random moon (from any planet):
229 ~your-urbit:dojo> +moon
230 :: produces
231 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
233### Variables
235You can use `=` to set an environment variable in `:dojo`, but there are
236a few reserved names that have special uses.
238#### `dir`
240Current working `%clay` desk and revision. Read / write.
242**Examples:**
244 ~your-urbit:dojo> =dir %/web
245 ~your-urbit:dojo> +ls %
247 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
249#### `lib`
251Current set of libraries (`/lib`) in your environment. Can also be set
252with `/+`. Read / write.
254**Examples:**
256 ~your-urbit:dojo> =lib ~[[%react ~]]
257 ~your-urbit:dojo> :: this also works:
258 ~your-urbit:dojo> /+ react
259 ~your-urbit:dojo> :: now we can use arms from lib/react.hoon
260 ~your-urbit:dojo> (react-vale:react %div)
262#### `sur`
264Current set of structures (`/sur`) in your environment. Can also be set
265with `/-`. Read / write.
267**Examples:**
269 ~your-urbit:dojo> =sur ~[[%sole ~]]
270 ~your-urbit:dojo> :: this also works:
271 ~your-urbit:dojo> /- sole
272 ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
273 ~your-urbit:dojo> `sole-effect:sole`[%bel ~]
275#### `now`
277The current (128-bit `@da`) time. Read-only.
279**Example:**
281 ~your-urbit:dojo> now
282 :: produces
283 ~2016.3.21..21.10.57..429a
285#### `our`
287The current urbit plot. Read-only.
289**Example:**
291 ~your-urbit:dojo> our
292 :: produces
293 ~your-urbit
295#### `eny`
297256 bits of entropy. Read-only.
299**Example:**
301 ~your-urbit:dojo> eny
302 :: produces
303 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o