Edit

Shell

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:

(% represents your current directory. For a complete explanation on urbit paths, see the filesystem section.)

Generators (files in /gen) are run with +:

Save output to a file in %clay with *:

Run system commands from :hood, like reload, using |:

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.

+code

Generates a code that is used to remotely log into your ship. No arguments.

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.

+pill/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.

+tree

Generate a recursive directory listing. Takes a path.

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).

|dojo/link / |dojo/unlink - Link / unlink a CLI app - may or may not be remote. Accepts an optional ship name and a mandatory app name.

|mass - Prints the current memory usage of all the kernel modules. No arguments.

|breload - Reloads a kernel module (vane) from source. Accepts any number of vane names.

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:

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:

Apps usually expect marked data, so & is often used here.

* - Save in %clay

Save a new .hoon file in /gen:

The last component of the path is expected to be the mark (or mime type).

. - Export to Unix

Export a noun to Unix with .:

Which creates a file at pier/.urb/put/foo/bar.baz.

This is very often used with +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:

Use a function to get the status code from an http request:

+ - - 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.

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:

now

The current (128-bit @da) time. Read-only.

Example:

our

The current urbit ship. Read-only.

Example:

eny

512 bits of entropy. Read-only.

Example:

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.

PreviousFilesystemNextShip Troubleshooting

Last updated