git.iko.soy/urbit.org
on roller-tutorial help sign in
urbit.org/content/using/os/shell.md
343 lines 7.4 kB history raw
1+++
2title = "Shell"
3template = "doc.html"
4weight = 2
5+++
7The Dojo is our shell; it processes system commands and returns output. It's a
8good place to quickly experiment with Urbit. On the surface the Dojo is just a
9Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
10data in Urbit.
12### Quickstart
14You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
15commands.
17#### Math
19Evaluate a Hoon expression (whitespace matters):
21```
22~your-urbit:dojo> (add 2 2)
23~your-urbit:dojo> %+ add 2 2
24```
26Tall-form Hoon may require multiple lines:
28```
29~your-urbit:dojo> %+ add
30~your-urbit:dojo< 2
31~your-urbit:dojo< 2
32```
34Hoon uses something called [the subject](/docs/hoon/hoon-school/the-subject-and-its-legs).
35The Dojo has its own subject and that's where Hoon's equivalent of variables,
36called faces, are stored.
38Use `=var` to save faces to the Dojo subject.
40```
41~your-urbit:dojo> =foo (add 2 2)
42```
44Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
45face in a `.hoon` file in this way.
47#### System commands
49Use `=dir` to set the current working directory:
51```
52~your-urbit:dojo> =dir %/gen
53```
55(`%` represents your current directory. For a complete explanation on urbit
56paths, see the [filesystem section](#filesystem).)
58Generators (files in `/gen`) are run with `+`:
60```
61~your-urbit:dojo> +hello 'world'
62```
64Save output to a file in `%clay` with `*`:
66```
67~your-urbit:dojo> *some/file/path/hoon 'hello world'
68```
70Run system commands from `:hood`, like `reload`, using `|`:
72```
73~your-urbit:dojo> |reload %eyre
74```
76### Generators
78Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
79directory. Many Dojo commands exist in the form of generators. The syntax for
80running a generator is `+genname` for a generator saved as `genname.hoon` in the
81`%base` desk. For generators on other desks, you can use the syntax
82`+desk!genname`.
84#### `+cat`
86Accepts a path and displays the file. Similar to Unix `cat`.
88```
89~your-urbit:dojo> +cat %/gen/curl/hoon
90```
92#### `+code`
94Generates a code that is used to remotely log into your ship. No
95arguments.
97```
98~your-urbit:dojo> +code
99```
101You can change your code to a new randomly generated one by entering `|code %reset`. Please note that this will prevent [Bridge](/docs/glossary/bridge)
102from being able to derive your code in the future.
104#### `+ls`
106Similar to Unix `ls`. Accepts a path.
108```
109~your-urbit:dojo> +ls %/gen
110~your-urbit:dojo> +ls /~talsur-todres/base/2/gen/program
111```
113#### `+solid`
115Compile the current state of the kernel and output a noun. Usually downloaded to
116a file in unix. This generator takes a series of desks to include as its
117argument. The first desk must be the base desk that contains the Arvo kernel,
118standard library and related files - typically `%base`.
120```
121~your-urbit:dojo> .urbit/pill +solid %base %garden %landscape %webterm %bitcoin
122```
124#### `+tree`
126Generate a recursive directory listing. Takes a path.
128```
129~your-urbit:dojo> +tree %/sys
130```
132### Hood
134The hood is the system daemon. See `gen/hood` and `app/hood`.
136`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
137an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
139```
140~your-urbit:dojo> |hi ~binzod "you there?"
141```
143`|link` / `|unlink` - Link / unlink a CLI app - may or may not be remote.
144Accepts an optional ship name and a mandatory app name.
146```
147~your-urbit:dojo> |link ~talsur-todres %octo
149~your-urbit:dojo> |link %chat-cli
150```
152`|mass` - Prints the current memory usage of all the kernel modules.
153No arguments.
155```
156~your-urbit:dojo> |mass
157```
159`|breload` - Reloads a kernel module (vane) from source. Accepts any
160number of vane names.
162```
163~your-urbit:dojo> |breload %clay %eyre
164```
166---
168### Dojo manual
170#### Sources and sinks
172A Dojo command is either a **source** or a **sink**. A source is just something
173that can be printed to your console or the result of some computation. A
174sink is an **effect**: a change to the filesystem, a network message, a
175change to your environment, or a typed message to an app.
177Sources can be chained together, but we can only produce one effect per
178command.
180#### Sinks
182#### `=` - Set variable
184Set any environment variable:
186```
187~your-urbit:dojo> =foo 42
188~your-urbit:dojo> (add 2 foo)
19044
191```
193Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
194variable in a `.hoon` file in this way.
196#### Special variables
198There are a few special variables that the Dojo maintains.
200#### `:` - Send to app
202`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
204Send a `helm-hi` message to `hood`:
206```
207~your-urbit:dojo> :hood &helm-hi 'hi'
208```
210Apps usually expect marked data, so `&` is often used here.
212#### `*` - Save in `%clay`
214Save a new `.hoon` file in `gen`:
216```
217~your-urbit:dojo> *%/gen/foo/hoon '# hello'
218```
220The last component of the path is expected to be the mark (or mime
221type).
223#### `.` - Export to Unix
225Export a noun to Unix with `.`:
227```
228~your-urbit:dojo> .foo/bar/baz (add 2 2)
229```
231Which creates a file at `pier/.urb/put/foo/bar.baz`.
233This is very often used with `+solid`:
235```
236~your-urbit:dojo> .urbit/pill +solid
237```
239Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
241### Sources
243#### `_` - Run a function
245Use `_` to run a gate (or function):
247Write an arbitrary function and pass data to it:
249```
250~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
252```
254Use a function to get the status code from an http request:
256```
257~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
258301
259```
261#### `+` `-` - HTTP requests
263`+http[s]://example.com` - sends a GET request
265`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
266JSON `"hi"` in the body.
268`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
269JSON `"hi"` in the body.
271Note that the first of these is a source while the last two are sinks.
273#### `+` - Generators
275Generators are simple Hoon scripts loaded from the filesystem. They live
276in `gen/`.
278An example of a generator that is built into your urbit is `+code`. It produces
279the code needed to log into your ship remotely.
281```
282~your-urbit:dojo> +code
283fintyr-haldet-fassev-solhex
284```
286Generators on desks other than `%base` can be run with the syntax
287`+desk!generator`.
289### Variables
291You can use `=` to set an environment variable in Dojo, but there are
292a few reserved names that have special uses.
294#### `dir`
296Current working `%clay` desk and revision. Read / write.
298**Examples:**
300```
301~your-urbit:dojo> =dir %/gen
302~your-urbit:dojo> +ls %
303404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
304```
306#### `now`
308The current (128-bit `@da`) time. Read-only.
310**Example:**
312```
313~your-urbit:dojo> now
314~2016.3.21..21.10.57..429a
315```
317#### `our`
319The current urbit ship. Read-only.
321**Example:**
323```
324~your-urbit:dojo> our
325~your-urbit
326```
328#### `eny`
330512 bits of entropy. Read-only.
332**Example:**
334```
335~your-urbit:dojo> eny
3360v27k.n4atp.fovm6.f7ggm.jdkn5.elct5.11tna.4qtid.g4so7.a1h6g.grp7u.qml4i.0ed1v.sl0r0.97d4b.6aepr.6v6qm.ls5ve.60kgb.j6521.2fqcb
337```
339### Troubleshooting
341If you encounter `%dy-edit-busy` while entering commands, it is
342because your Dojo is blocked on a timer or an HTTP request. Type backspace
343and your Dojo will end the blocked command.