The Dojo is our shell; it processes system commands and returns output. It's a good place to quickly experiment with Urbit. On the surface the Dojo is just a Hoon REPL. On the inside, the Dojo is a system for operating on and transforming data in Urbit.
Quickstart
You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system commands.
Math
Evaluate a Hoon expression (whitespace matters):
~your-urbit:dojo> (add 2 2)~your-urbit:dojo> %+ add 2 2
Tall-form Hoon may require multiple lines:
~your-urbit:dojo> %+ add~your-urbit:dojo< 2~your-urbit:dojo< 2
Hoon uses something called the subject. The Dojo has its own subject and that's where Hoon's equivalent of variables, called faces, are stored.
Use =var to save faces to the Dojo subject.
~your-urbit:dojo> =foo (add 2 2)
Note, however, that =var is Dojo syntax, not Hoon syntax. You cannot bind a face in a .hoon file in this way.
System commands
Use =dir to set the current working directory:
~your-urbit:dojo> =dir %/gen
(% represents your current directory. For a complete explanation on urbit paths, see the filesystem section.)
Generators (files in /gen) are run with +:
~your-urbit:dojo> +hello 'world'
Save output to a file in %clay with *:
~your-urbit:dojo> *some/file/path/hoon 'hello world'
Run system commands from :hood, like reload, using |:
~your-urbit:dojo> |reload %eyre
Generators
Generators are short Hoon scripts, saved as .hoon files in the /gen directory. Many Dojo commands exist in the form of generators. The syntax for running a generator is +genname for a generator saved as genname.hoon in the %base desk. For generators on other desks, you can use the syntax +desk!genname.
+cat
Accepts a path and displays the file. Similar to Unix cat.
~your-urbit:dojo> +cat %/gen/curl/hoon
+code
Generates a code that is used to remotely log into your ship. No arguments.
~your-urbit:dojo> +code
You can change your code to a new randomly generated one by entering |code %reset. Please note that this will prevent Bridge from being able to derive your code in the future.
+ls
Similar to Unix ls. Accepts a path.
~your-urbit:dojo> +ls %/gen~your-urbit:dojo> +ls /~talsur-todres/base/2/gen/program
+solid
Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. This generator takes a series of desks to include as its argument. The first desk must be the base desk that contains the Arvo kernel, standard library and related files - typically %base.
~your-urbit:dojo> .urbit/pill +solid %base %garden %landscape %webterm %bitcoin
+tree
Generate a recursive directory listing. Takes a path.
~your-urbit:dojo> +tree %/sys
Hood
The hood is the system daemon. See gen/hood and app/hood.
|hi - Sends a direct message. Sort of like Unix write. Accepts an urbit name (@p) and a string (tape, which is text wrapped with double-quotes).
~your-urbit:dojo> |hi ~binzod "you there?"
|link / |unlink - Link / unlink a CLI app - may or may not be remote. Accepts an optional ship name and a mandatory app name.
~your-urbit:dojo> |link ~talsur-todres %octo~your-urbit:dojo> |link %chat-cli
|mass - Prints the current memory usage of all the kernel modules. No arguments.
~your-urbit:dojo> |mass
|breload - Reloads a kernel module (vane) from source. Accepts any number of vane names.
~your-urbit:dojo> |breload %clay %eyre
Dojo manual
Sources and sinks
A 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 a typed message to an app.
Sources can be chained together, but we can only produce one effect per command.
Sinks
= - Set variable
Set any environment variable:
~your-urbit:dojo> =foo 42~your-urbit:dojo> (add 2 foo)44
Make sure to note that =var is Dojo syntax, not Hoon syntax. You cannot bind a variable in a .hoon file in this way.
Special variables
There are a few special variables that the Dojo maintains.
: - Send to app
:app goes to a local app, :~ship/app goes to the app on ~ship.
Send a helm-hi message to hood:
~your-urbit:dojo> :hood &helm-hi 'hi'
Apps usually expect marked data, so & is often used here.
* - Save in %clay
Save a new .hoon file in gen:
~your-urbit:dojo> *%/gen/foo/hoon '# hello'
The last component of the path is expected to be the mark (or mime type).
. - Export to Unix
Export a noun to Unix with .:
~your-urbit:dojo> .foo/bar/baz (add 2 2)
Which creates a file at pier/.urb/put/foo/bar.baz.
This is very often used with +solid:
~your-urbit:dojo> .urbit/pill +solid
Which outputs a new urbit.pill to pier/.urb/put/urbit.pill
Sources
_ - Run a function
Use _ to run a gate (or function):
Write an arbitrary function and pass data to it:
~your-urbit:dojo> _|=([[email protected]] (mul a 3)) 39
Use a function to get the status code from an http request:
~your-urbit:dojo> _|=([[email protected] q=* r=*] p) +http://google.com301
+ - - HTTP requests
+http[s]://example.com - sends a GET request
+http[s]://example.com &json [%s 'hi'] - sends a POST request with the JSON "hi" in the body.
-http[s]://example.com &json [%s 'hi'] - sends a PUT request with the JSON "hi" in the body.
Note that the first of these is a source while the last two are sinks.
+ - Generators
Generators are simple Hoon scripts loaded from the filesystem. They live in gen/.
An example of a generator that is built into your urbit is +code. It produces the code needed to log into your ship remotely.
~your-urbit:dojo> +codefintyr-haldet-fassev-solhex
Generators on desks other than %base can be run with the syntax +desk!generator.
Variables
You can use = to set an environment variable in Dojo, but there are a few reserved names that have special uses.
dir
Current working %clay desk and revision. Read / write.
Examples:
~your-urbit:dojo> =dir %/gen~your-urbit:dojo> +ls %404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
now
The current (128-bit @da) time. Read-only.
Example:
~your-urbit:dojo> now~2016.3.21..21.10.57..429a
our
The current urbit ship. Read-only.
Example:
~your-urbit:dojo> our~your-urbit
eny
512 bits of entropy. Read-only.
Example:
~your-urbit:dojo> eny0v27k.n4atp.fovm6.f7ggm.jdkn5.elct5.11tna.4qtid.g4so7.a1h6g.grp7u.qml4i.0ed1v.sl0r0.97d4b.6aepr.6v6qm.ls5ve.60kgb.j6521.2fqcb
Troubleshooting
If you encounter %dy-edit-busy while entering commands, it is because your Dojo is blocked on a timer or an HTTP request. Type backspace and your Dojo will end the blocked command.