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.


    You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system commands.


    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 %/web

    (% 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 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.


    Accepts a path and displays the file. Similar to Unix cat.

    ~your-urbit:dojo> +cat %/gen/curl/hoon


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

    ~your-urbit:dojo> +code


    Retrives data from a URL. Accepts a tape. Similar to Unix curl.

    ~your-urbit:dojo> +curl ""


    Just prints the argument. Accepts a @ta.

    ~your-urbit:dojo> +hello 'mars'


    Similar to Unix ls. Accepts a path.

    ~your-urbit:dojo> +ls %/web
    ~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes


    Generates a random moon from a planet. No arguments.

    ~your-urbit:dojo> +moon


    Compile the current state of the kernel and output a noun. Usually downloaded to a file in unix. No arguments.

    ~your-urbit:dojo> .urbit/pill +solid


    Testrunner. Can test multiple generators at once, conventionally ones in the /test folder. Takes a path.

    ~your-urbit:dojo> +test /lib


    Generate a ticket for an urbit ship. Takes an urbit name (@p).

    ~your-urbit:dojo> +ticket ~talsur-todres-your-urbit


    Generate a recursive directory listing. Takes a path.

    ~your-urbit:dojo> +tree %/web


    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 remote app. Accepts an Urbit name and an app name.

    ~your-urbit:dojo> |link ~talsur-todres %octo

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

    ~your-urbit:dojo> |mass

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

    ~your-urbit:dojo> |reload %clay %eyre

    |reset - Reloads hoon.hoon and all modules. No arguments.

    ~your-urbit:dojo> |reset

    |start - Starts an app. Accepts an app name.

    ~your-urbit:dojo> |start %curl


    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 typed message to an app.

    Sources can be chained together, but we can only produce one effect per command.


    = - Set variable

    Set any environment variable:

    ~your-urbit:dojo> =foo 42
    ~your-urbit:dojo> (add 2 foo)

    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 .udon (Udon) file in web:

    ~your-urbit:dojo> *%/web/foo/udon '# 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


    & - Mark conversion

    Convert between marks using &, with the destination mark first. You can stack multiple mark conversions together, and some marks can only be converted to specific other marks. In this example, Udon is converted to &hymn (a mark which supplies the html, head, body and closing tags) first, before being converted to HTML:

    ~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
    '<html><head></head><body><h1 id="hello">hello</h1></body></html>'

    Performing a conversion straight from Udon to the &hymn mark reveals a bit more about its mark conversion:

    ~your-urbit:dojo>&hymn &udon ';h1#hello: hello'
    [[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]

    As does converting straight from Udon to HTML:

    ~your-urbit:dojo>&html &udon ';h1#hello: hello'
    ';h1#hello: hello'

    _ - Run a function

    Use _ to run a gate (or function):

    Write an arbitrary function and pass data to it:

    ~your-urbit:dojo> _|=([a=@] (mul a 3)) 3

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

    ~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +

    + - - HTTP requests

    +http[s]:// - sends a GET request

    +http[s]:// &json [%s 'hi'] - sends a POST request with the JSON "hi" in the body.

    -http[s]:// &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> +code


    You can use = to set an environment variable in Dojo, but there are a few reserved names that have special uses.


    Current working %clay desk and revision. Read / write.


    ~your-urbit:dojo> =dir %/web
    ~your-urbit:dojo> +ls %
    404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/


    Current set of libraries (/lib) in your environment. Can be set with /+. Read / write.


    ~your-urbit:dojo> /+  number-to-words

    Now we can use arms from lib/number-to-words.hoon

    ~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)


    Current set of structures (/sur) in your environment. Can be set with /-. Read / write.


    ~your-urbit:dojo> /-  sole

    Now we can use arms in sur/sole.hoon.

    ~your-urbit:dojo> `sole-effect:sole`[%bel ~]


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


    ~your-urbit:dojo> now


    The current urbit ship. Read-only.


    ~your-urbit:dojo> our


    512 bits of entropy. Read-only.


    ~your-urbit:dojo> eny


    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.