git.iko.soy/urbit.org
on 140ac0e help sign in
urbit.org/docs/using/shell.md
271 lines 6.8 kB history raw
1---
2next: true
3sort: 5
4title: Shell (:dojo)
5---
7<div class="row">
8<div class="col-md-8">
12## `:dojo` (shell)
14The `:dojo` is the place to quickly experiment with Urbit. At first glance the `:dojo` is just a Hoon REPL. Looking a bit deeper the `:dojo` is set up to make operating on and transforming data in Urbit easy.
16</div>
17</div>
19## Quickstart
21Evaluate a hoon expression:
23 ~your-urbit:dojo> (add 2 2)
24 ~your-urbit:dojo> %+ add 2 2
26Tall form Hoon will be prompted for:
28 ~your-urbit:dojo> %+ add
29 ~your-urbit:dojo< 2
30 ~your-urbit:dojo< 2
32Use `=var` to save a shell variable:
34 ~your-urbit:dojo> =foo (add 2 2)
36Use `=dir` to set the current working directory:
38 ~your-urbit:dojo> =dir %/web
40Generators (files in `/gen`) are run with `+`:
42 ~your-urbit:dojo> +hello 'world'
44Save output to a file in `%clay` with `*`:
46 ~your-urbit:dojo> *some/file/path/hoon 'hello world'
48Run system commands from `:hood`, like `reload`, using `|`:
50 ~your-urbit:dojo> |reload %eyre
52## Manual
54<h3 class="first child">Sources and sinks</h3>
56A dojo command is either a source or a sink. A source is just something that can be printed to your console or the result of some computation. A sink is an *effect*: a change to the filesystem, a network message, a change to your environment, or typed message to an app.
58Sources can be chained together, but we can only produce one effect per command.
60### Sinks
62#### `=` - Set variable
64Set any envronment variable:
66 ~your-urbit:dojo> =foo 42
67 ~your-urbit:dojo> (add 2 foo)
69 44
71(There are a few special variables that the dojo expects. See below.)
73#### `:` - Send to app
75`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
77Send a `helm-hi` message to `hood`:
79 ~your-urbit:dojo> :hood &helm-hi 'hi'
81App usually expect marked data, so `&` is often used here.
83#### `*` - Save in `%clay`
85Save a new `md` file in `web`:
87 ~your-urbit:dojo> *%/web/foo/md '# hello'
89The last component of the path is expected to be the mark (or mime type).
91#### `.` - Download to Unix
93Download a noun to Unix with `.`:
95 ~your-urbit:dojo> .foo/bar/baz (add 2 2)
97Which creates a file at `pier/.urb/put/foo/bar.baz`.
99This is very often used with `+solid`:
101 ~your-urbit:dojo> .urbit/pill +solid
103Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
105### Sources
107#### `&` - Mark conversion
109Convert between marks using `&`:
111 ~your-urbit:dojo> &html &md '# hello'
112 :: produces
113 '<html><head></head><body><div><h1 id="-hello">hello</h1></div></body></html>'
115#### `_` - Run a function
117Use `_` to run a gate (or function):
119 :: assign an arbitrary function and pass data to it
120 ~your-urbit:dojo> _|=({a/@} (mul a 3)) 3
121 :: produces
122 9
123 :: assign an arbitrary function to get the status code from an http request
124 ~your-urbit:dojo> _|=({p/@ud q/* r/*} p) +http://google.com
125 :: produces
126 301
128#### `+` `-` - HTTP requests
130`+http[s]://example.com` - sends a GET request
132`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the JSON `"hi"` in the body.
134`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the JSON `"hi"` in the body.
136#### `+` - Generators
138Generators are simple hoon scripts loaded from the filesystem. They live in `gen/`.
140Create a random moon (from any planet):
142 ~your-urbit:dojo> +moon
143 :: produces
144 "moon: ~docsun-tamtem-your-urbit; ticket: ~bartug-hodbyr-fognum-ralmud"
146### Variables
148You can use `=` to set an environment variable in `:dojo`, but there are a few reserved names that have special uses.
150#### `dir`
152Current working `%clay` desk and revision. Read / write.
154**Examples:**
156 ~your-urbit:dojo> =dir %/web
157 ~your-urbit:dojo> +ls %
159 404/hoon docs/ dojo/hoon lib/ listen/hoon md static/md talk/ tree/main/
161#### `lib`
163Current set of libraries (`/lib`) in your environment. Can also be set with `/+`. Read / write.
165**Examples:**
167 ~your-urbit:dojo> =lib ~[[%react ~]]
168 ~your-urbit:dojo> :: this also works:
169 ~your-urbit:dojo> /+ react
170 ~your-urbit:dojo> :: now we can use arms from lib/react.hoon
171 ~your-urbit:dojo> (react-vale:react %div)
173#### `sur`
175Current set of structures (`/sur`) in your environment. Can also be set with `/-`. Read / write.
177**Examples:**
179 ~your-urbit:dojo> =sur ~[[%sole ~]]
180 ~your-urbit:dojo> :: this also works:
181 ~your-urbit:dojo> /- sole
182 ~your-urbit:dojo> :: now we can use arms in sur/sole.hoon
183 ~your-urbit:dojo> `sole-effect:sole`[%bel ~]
185#### `now`
187The current (128-bit `@da`) time. Read-only.
189**Example:**
191 ~your-urbit:dojo> now
192 :: produces
193 ~2016.3.21..21.10.57..429a
195#### `our`
197The current urbit plot. Read-only.
199**Example:**
201 ~your-urbit:dojo> our
202 :: produces
203 ~your-urbit
205#### `eny`
207256 bits of entropy. Read-only.
209**Example:**
211 ~your-urbit:dojo> eny
212 :: produces
213 0v1o.m2vio.j5ieb.7tq84.5kcnp.gjn04.9gl2e.tkj5v.0oqk3.iugk8.rhu6o
215### Generators
217**`+cat`** - Similar to Unix `cat`. Accepts a path.
219 ~your-urbit:dojo> +cat %/web/md
220 ~your-urbit:dojo> +cat /~talsur-todres/home/2/web/notes/md
222**`+curl`** - Similar to Unix `curl`. Accepts a `tape`.
224 ~your-urbit:dojo> +curl "http://nyt.com"
226**`+hello`** - Just prints the argument. Accepts a `@ta`.
228 ~your-urbit:dojo> +hello 'mars'
230**`+ls`** - Similar to Unix `ls`. Accepts a path.
232 ~your-urbit:dojo> +ls %/web
233 ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
235**`+moon`** - Generate a random moon from a planet. No arguments.
237**`+solid`** - Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.
239 ~your-urbit:dojo> .urbit/pill +solid
241**`+ticket`** - Generate a ticket for an Urbit plot. Takes an Urbit name (`@p`).
243 ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
245**`+tree`** - Generate a recursive directory listing. Takes a path.
247 ~your-urbit:dojo> +tree %/web
249### Hood
251The hood is the system daemon. See `gen/hood` and `app/hood`.
253**`|hi`** - Sends a direct message. Sort of like Unix `write`. Accepts an urbit name (`@p`) and a string (`cord`).
255 ~your-urbit:dojo> |hi ~doznec 'you there?'
257**`|link`** / **`|unlink`** - Link / unlink a remote app. Accepts an Urbit name and an app name.
259 ~your-urbit:dojo> |link ~talsur-todres %octo
261**`|mass`** - Prints the current memory usage of all the kernel modules. No arguments.
263**`|reload`** - Reloads a kernel module (vane) from source. Accepts any number of vane names.
265 ~your-urbit:dojo> |reload %clay %eyre
267**`|reset`** - Reloads `hoon.hoon`. No arguments.
269**`|start`** - Starts an app. Accepts an app name.
271 ~your-urbit:dojo> |start %curl